# Developer Platform Welcome to your team’s developer platform

Kognitos Documentation

Learn how to automate faster and smarter with our guides, tutorials, and references.

Explore the Docs

{% columns %} {% column width="50%" %} ## Get Started in Minutes Kognitos helps you automate work quickly. Describe what you want to happen in natural language and let Kognitos handle the rest — no coding required. Get Started {% endcolumn %} {% column width="50%" %}
{% endcolumn %} {% endcolumns %}

{% columns %} {% column width="41.66666666666667%" %}
{% endcolumn %} {% column width="58.33333333333333%" %} ## Learn More Explore our guides to work smarter and unlock the full power of Kognitos, platform guides, best practices, and step-by-step instructions to make automation faster, easier, and more reliable. About Kognitos Our Blog {% endcolumn %} {% endcolumns %} ## Guides Discover our guides to get started, navigate the platform, and connect integrations with ease.

:book-open:

Getting Started

Learn the basics of Kognitos, from onboarding to fundamental concepts, so you can start building automations quickly./spaces/x2dWUsD9HEagjfZqvgHO/pages/IWwQjOB6HKwhco3Ts2pG

:layer-group:

Platform

Understand the different components of the Kognitos platform and learn how to create and manage your automations./spaces/x2dWUsD9HEagjfZqvgHO/pages/ZLviLvukemZavmgVDQCo

:grid-2-plus:

Integrations

Discover how to connect Kognitos to your favorite systems, manage connections, and handle credentials with ease./spaces/x2dWUsD9HEagjfZqvgHO/pages/BfZFhasPovJ8Ss5KZsQX
# Introduction Discover how Kognitos makes automation simple and reliable. ## What is Kognitos? Kognitos is an **automation platform** for building, running, and maintaining business processes. Instead of writing code or configuring complex workflows, you describe what the workflow should do in plain English, and Kognitos turns that description into a **deterministic, executable automation**. {% embed url="" %} ## Who Can Use Kognitos? Kognitos is designed for anyone who needs to automate work, whether you're a business analyst streamlining invoice approvals, an operations manager coordinating data across systems, or a developer eliminating repetitive tasks. {% hint style="success" %} If you can describe the task, Kognitos can automate it — no matter your technical background. {% endhint %} ## What Can You Automate? Kognitos handles workflows across departments:
DepartmentCommon Automations
FinanceInvoice processing, expense approvals, reconciliation
OperationsOrder fulfillment, inventory updates, data synchronization
HREmployee onboarding, time-off requests, compliance tracking
SalesLead routing, CRM updates, quote generation
Information TechnologyUser provisioning, ticket routing, system monitoring
{% embed url="" %} ## How Does Kognitos Work? With Kognitos, you describe automation tasks in **natural language** *(plain English).* Kognitos understands business logic without special syntax or commands and turns it into an executable workflow. Here's how that process works: {% stepper %} {% step %} **Describe Your Task** Write out your business logic as a sequence of instructions. For example:
Invoice Processing > When a new invoice is received, extract the invoice number, amount, and due date. Check whether the vendor exists in the system. If the vendor exists and the amount is less than $10,000, create the invoice record and mark it as approved.
Employee Onboarding > When a new employee is added to the onboarding list, create accounts in the required systems and assign them to the correct department and role.
Updating Spreadsheet Data > Every weekday morning, check the spreadsheet for new rows. For each new row, validate the data and create a corresponding record in the system. After processing, mark the row as completed.
{% endstep %} {% step %} **Clarifying Through Conversation** Kognitos interprets your instructions to transform them into an **executable** automation that can run from start to finish. If something is unclear or missing, Kognitos asks questions and refines your instructions until it has everything it needs to build the automation correctly. {% endstep %} {% step %} **Building the Workflow** Once Kognitos understands your task, it creates a structured, step-by-step workflow. This is a **deterministic** process that executes the same way every time. {% endstep %} {% step %} **Run, Review, & Refine** Execute your automation, review the results, and adjust instructions as your process evolves. Kognitos makes it easy to handle exceptions and update workflows without starting over. {% endstep %} {% endstepper %} ## What Makes Kognitos Different? Kognitos is not a chat assistant or a suggestion tool. It combines conversation with real-world execution, so you don’t just get suggestions — you get workflows that actually get work done.
Kognitos vs. AI Assistants AI assistants generate suggestions, summaries, or responses based on your prompts. Kognitos goes a step further by turning plain English instructions into executable workflows that perform real actions, track progress, and produce predictable, repeatable results.
Kognitos vs. Low-Code / No-Code Platforms Most low-code platforms require drag-and-drop builders and preconfigured templates. Kognitos skips the visual configuration entirely. Just describe your workflow in plain English, and it builds the automation for you.
Kognitos vs. RPA (Robotic Process Automation) Traditional RPA automates by scripting UI clicks, which breaks when interfaces change. Kognitos executes workflows using business logic, not screen scraping, making automations more reliable and easier to maintain.
Kognitos vs. Custom Scripts Writing custom scripts gives you full control but requires development time, testing, and ongoing maintenance. Kognitos delivers the same reliability without code. Update workflows by editing instructions, not debugging scripts.
# Onboarding Get started by creating and setting up your Kognitos account. ## Overview Welcome! In just a few minutes, you'll have your Kognitos account ready to go. This guide will walk you through account creation, organization setup, and initial workspace creation. ## 1. Account Creation You'll first need to create a Kognitos account to get started. {% stepper %} {% step %} **Getting Started** Navigate to [**app.us-1.kognitos.com**](https://app.us-1.kognitos.com/) to sign up. {% endstep %} {% step %} **Sign Up** Choose how you'd like to sign up:
Email Click **Sign up here**, enter your email address, and click Continue.
Google Account Click **Continue with Google** and sign in with your Google credentials.
Microsoft Account Click **Continue with Microsoft Account** and sign in with your Microsoft credentials.
{% endstep %} {% step %} **Verify Your Identity** Check your inbox for an email from **Kognitos** with the subject line *"Login to Kognitos"*. The email will contain a **6-digit verification code**. Copy the code and enter it into Kognitos, then click Continue.
{% hint style="warning" %} **Didn't get the verification code?** Check your spam folder or click **Resend** after 60 seconds. {% endhint %} {% endstep %} {% step %} **Profile Setup** Once you've verified your identity, you need to set up your profile. Enter your **First Name**, **Last Name**, and **Company**. Then, click Continue.
{% endstep %} {% endstepper %} You’ll then be logged into Kognitos and guided through setting up your organization and initial workspace. ## 2. Organization Setup Set up your organization to manage users and shared resources. Enter your **Organization name** and your **Role** in that organization *(optional).* Then, click Create organization . {% hint style="info" %} An **organization** is your company or team's home on Kognitos. Every user must belong to one. Organizations allow you to manage members, billing, and settings in one place. {% endhint %}
## 3. Workspace Setup Create a **workspace** where you’ll build and run automations. Enter a **workspace name** and **workspace domain** *(optional)*. Then, click Create workspace. {% hint style="info" %} A **workspace** is a dedicated section within an organization where your automation projects live. You can create multiple workspaces later to organize different processes, teams, or initiatives. {% endhint %}
## 4. Tell Us What Matters Tell us what matters to you to better tailor your experience. Select your focus, then click Continue. {% hint style="success" %} This step is **optional** — click Skip for now to continue without sharing. {% endhint %}
## Ready to Automate? Your account is ready! Head to the [**Quick Start**](/guides/getting-started/quick-start) guide to create your first draft or explore the [**Fundamentals**](/guides/getting-started/fundamentals) page to learn more about how Kognitos works. # Fundamentals Understand the foundational concepts of Kognitos. ## Overview This guide covers the essential concepts you need to understand how Kognitos works. You'll learn core concepts, the automation lifecycle, and how Kognitos works. ## Structure Let's start with how your work is organized and structured in Kognitos. Three levels are used to organize your work: **Organizations** *(your company)*, **Workspaces** *(teams or projects)*, and **Automations** *(individual workflows)*. {% @mermaid/diagram content="graph TB subgraph Org\[" **Organization** "] subgraph WS1\[" **Workspace** "] B1\[Automation] B2\[Automation] B3\[Automation] end end style Org fill:#2A2A2A,stroke:#E0E0E0,stroke-width:3px,color:#FFFFFF style WS1 fill:#3A3A3A,stroke:#A0A0A0,stroke-width:2px,color:#FFFFFF style B1 fill:#F2FB90,stroke:#D4E157,stroke-width:2px,color:#1C1C1B style B2 fill:#F2FB90,stroke:#D4E157,stroke-width:2px,color:#1C1C1B style B3 fill:#F2FB90,stroke:#D4E157,stroke-width:2px,color:#1C1C1B" %} ### Organization An **organization** is your company's account: the top-level container for everything in Kognitos. Every user belongs to one. Organizations allow you to manage users, roles, and settings in one place. ### Workspace A **workspace** is a dedicated section within an organization where one or more automation projects live. Think of them as folders that keep your work organized. You can create multiple workspaces within an organization to organize different processes, teams, or initiatives. ### Automations **Automations** are the individual tasks or processes you want to execute. Each automation lives in a workspace and represents a specific workflow, like "Validate Invoice" or "Send Payment Reminder". Every automation begins as a **draft**, allowing you to edit and test it before publishing. ### Example Structure Here's how this might look for a company like **Acme Corp**, with separate workspaces for **Finance**, **Logistics**, and **HR** teams - each containing their own automations. {% @mermaid/diagram content="graph TD AcmeCorp\["Acme Corp"] Finance\["Finance
───────────────
Validate Invoice
Send Payment Reminder
Reconcile Payments"] Logistics\["Logistics
───────────────
Track Shipments
Update Inventory
Generate Labels"] HR\["HR
───────────────
Onboard New Employee
Process Time Off Request
Generate Payroll Report"] ``` AcmeCorp --> Finance AcmeCorp --> Logistics AcmeCorp --> HR style AcmeCorp fill:#5B5C59,stroke:#F2FB90,stroke-width:3px,color:#F2FB90 style Finance fill:#1C1C1B,stroke:#CBCCC5,stroke-width:2px,color:#F3F4ED style Logistics fill:#1C1C1B,stroke:#CBCCC5,stroke-width:2px,color:#F3F4ED style HR fill:#1C1C1B,stroke:#CBCCC5,stroke-width:2px,color:#F3F4ED ``` " %} ## The Automation Lifecycle In Kognitos, automations move through three distinct phases: {% @mermaid/diagram content="graph LR A\[1. Draft] --> B\[2. Publish] B --> C\[3. Monitor] C --> A ``` style A fill:#F2FB90,stroke:#D4E157,stroke-width:2px,color:#1C1C1B style B fill:#F2FB90,stroke:#D4E157,stroke-width:2px,color:#1C1C1B style C fill:#F2FB90,stroke:#D4E157,stroke-width:2px,color:#1C1C1B" %} ``` {% stepper %} {% step %} #### 1. Draft Every automation begins as a **draft**, allowing you to build and refine your instructions through conversation with Kognitos. Drafts are editable workflows that evolve as you make changes. {% endstep %} {% step %} #### 2. Publish When a draft is ready, you publish it to create an automation. An **automation** is the locked, production-ready version of a draft, designed for reliable and repeatable execution. {% endstep %} {% step %} #### 3. Monitor After publishing, your automation is live and ready to run independently. You don't need to do anything else, but you can **monitor** as needed - observe how your automation performs, check results, handle exceptions, and refine guidance. You can also **archive** completed runs to keep your run history organized. {% endstep %} {% endstepper %} This lifecycle is iterative. When changes are needed, you return to the draft, update the logic, publish, run, and monitor a new version. ## Inputs & Outputs Automations transform data. Understanding how data flows into and out of your automations is key to building workflows that connect your business processes. ### Inputs **Inputs** are the data your automation needs to run. Kognitos identifies inputs based on your task instructions. For example, if you write "*validate each invoice in the uploaded spreadsheet*," the system knows it needs a spreadsheet file as input. Inputs can be **manual** or **automatic**: #### **Manual** * Files (PDFs, Excel spreadsheets, CSVs) * Text (letters, words, numbers, dates) * References (invoice numbers, customer IDs, order codes) #### **Automatic** *(scheduled or event-triggered)* * New files uploaded to a folder * Rows added to a spreadsheet * Form submissions from your website * API responses from external systems ### Outputs **Outputs** are what your automation produces - representing completed work and generated results. There are different types of outputs: #### **Data** * Updated spreadsheets with processed records * Database entries created or modified * Generated reports or summaries #### **Communication** * Emails sent to specific recipients * Notifications triggered in other systems * API calls made to external systems ## Summary Kognitos organizes your work into three levels: **organizations** *(your company)*, **workspaces** *(teams or projects)*, and **automations** *(individual workflows)*. Automations follow a simple lifecycle: build as a **draft**, **publish** when ready, and **evaluate** results in production. {% hint style="success" %} Ready to see it in action? Head to the [**Quick Start**](/guides/getting-started/quick-start) guide to create your first automation. {% endhint %} # Quick Start Get up and running with Kognitos in just a few minutes. ## Overview Ready to see Kognitos in action? In the next few minutes, you'll create your first automation by describing a task in plain English. No code — just conversation. ## Logging In Get started by logging into your account. {% hint style="success" %} **New Here?** Check out the [**Onboarding**](/guides/getting-started/onboarding) guide to create and set up your account. {% endhint %}
How do I log into Kognitos? 💡 1. Navigate to [**app.us-1.kognitos.com**](https://app.us-1.kognitos.com/)**.** 2. Enter your **email** *or* select **Continue with Google** . 3. Check your inbox for an email from **Kognitos** with the subject line *"Login to Kognitos"*. The email will contain a 6-digit verification code.
4. Copy the code and enter it into Kognitos, then click **Continue** to verify your identity. {% hint style="info" %} See [**Onboarding**](/guides/getting-started/onboarding) for more details. {% endhint %}
## Your First Draft Let's create your first draft. In Kognitos, an **automation** is a workflow that handles a specific business task and always starts as a **draft**, allowing you to build and test safely. {% stepper %} {% step %} #### **Navigate to Drafts** Click on **Drafts** in the left navigation menu. You'll see a prompt waiting for your instructions.
{% endstep %} {% step %} #### **Describe Your Task** Describe what you want to automate in plain English. You can be as detailed or high-level as you like. You'll refine it together with Kognitos.
{% hint style="success" %} Have an SOP, process document, or workflow description? Click the **+** button to upload it directly. Kognitos will read your file and generate a starting point for your automation. {% endhint %} {% endstep %} {% step %} #### **Refine** Kognitos will chat with you to understand exactly what you want to automate. It'll ask clarifying questions about your process, help you connect any tools you need, and make sure it has all the details to build your automation correctly. **You might see questions like:** * "Where are your documents stored?" * "What format are the invoices in — PDF or CSV?" * "Should the $500 threshold include or exclude tax?" {% hint style="success" %} **Think of this as Kognitos gathering everything it needs to get started:** the details of your process, access to your tools, and clarity on any decisions the automation needs to make. {% endhint %}
{% endstep %} {% step %} #### **Review** Once Kognitos understands your task and has everything it needs to proceed, it will generate the automation steps. Review the workflow to make sure it matches your expectations. You can edit continue the conversation to make adjustments as needed.
{% endstep %} {% step %} #### **Add Inputs** Once you've reviewed the automation document, run and test it by providing inputs. **Inputs** are pieces of information your automation needs at the start of (or during) a run. They can come from you, the Kognitos platform, or external systems. For example: * A folder path where documents are stored * A date range for processing invoices * A recipient email address
How to Add Inputs? 🔢 1. Click the **Inputs & Triggers** button at the bottom of the workflow document.
2. Review the detected inputs — the system automatically found them from your instructions. 3. Add in any required values: 1. **Text fields** *(names, numbers, references)* 2. **File uploads** *(PDFs, Excel files, images)* 3. **Dates, times, or selections from dropdowns** 4. Click **Save** to save your inputs.
{% hint style="danger" %} If you click ▶️ to **run** the draft without providing inputs first, you'll see the **Almost There - Add Inputs First** screen prompting you to add them. {% endhint %} {% endstep %} {% step %} #### **Run** Click on the ▶️ button in the top-right to execute your workflow. After the run completes, you can: * **Review** the outputs * **Back to edit** the automation if needed * **Run again** to re-execute * **Publish** the draft to turn it into an automation * **Chat** with the **Run Assistant** for further questions or clarifications {% endstep %} {% endstepper %} ## What's Next? Now that you've created your first automation, you're ready to explore more: * [**Learn how automations work**](/guides/getting-started/fundamentals) — understand the foundational concepts * [**Publish**](/guides/platform/automations) — move your automated workflow into production # Drafts Drafts are your workspace for building and refining automations before publishing. ## Overview Every automation in Kognitos begins as a **draft**, allowing you to build and refine your instructions through conversation with Kognitos. Drafts are editable workflows that evolve as you make changes. ## Dashboard Click **Drafts** in the left navigation menu and scroll down below the chat to see a list of your drafts. You'll see the draft name, last modified date, draft version, and published version *(if applicable)*. You can also search for drafts by title or filter by creator.
### Actions Click on any draft to open it. Create a new draft by clicking the **+ New Draft** button in the top right. To access additional options, click **⋮** on any draft to: * **Rename** the draft for better organization * **Delete** the draft if you no longer need it * **Publish** the draft to turn it into an automation *(this option will be disabled if Kognitos needs more information from you first)*
## Creating a New Draft These steps describe how to create a **new draft**: {% stepper %} {% step %} #### **Navigate to Drafts** Click on **Drafts** in the left navigation menu. You'll see a prompt waiting for your instructions.
{% endstep %} {% step %} #### **Describe Your Task** Describe what you want to automate in plain English. You can be as detailed or high-level as you like. You'll refine it together with Kognitos.
{% hint style="success" %} Have an SOP, process document, or workflow description? Click the **+** button to upload it directly. Kognitos will read your file and generate a starting point for your automation. {% endhint %} {% endstep %} {% step %} #### **Refine** Kognitos will chat with you to understand exactly what you want to automate. It'll ask clarifying questions about your process, help you connect any tools you need, and make sure it has all the details to build your automation correctly. **You might see questions like:** * "Where are your documents stored?" * "What format are the invoices in — PDF or CSV?" * "Should the $500 threshold include or exclude tax?" {% hint style="success" %} **Think of this as Kognitos gathering everything it needs to get started:** the details of your process, access to your tools, and clarity on any decisions the automation needs to make. {% endhint %}
{% endstep %} {% step %} #### **Review** Once Kognitos understands your task and has everything it needs to proceed, it will generate the automation steps. Review the workflow to make sure it matches your expectations. You can edit continue the conversation to make adjustments as needed.
{% endstep %} {% step %} #### **Add Inputs** Once you've reviewed the automation document, run and test it by providing inputs. **Inputs** are pieces of information your automation needs at the start of (or during) a run. They can come from you, the Kognitos platform, or external systems. For example: * A folder path where documents are stored * A date range for processing invoices * A recipient email address
How to Add Inputs? 🔢 1. Click the **Inputs & Triggers** button at the bottom of the workflow document.
2. Review the detected inputs — the system automatically found them from your instructions. 3. Add in any required values: 1. **Text fields** *(names, numbers, references)* 2. **File uploads** *(PDFs, Excel files, images)* 3. **Dates, times, or selections from dropdowns** 4. Click **Save** to save your inputs.
{% hint style="danger" %} If you click ▶️ to **run** the draft without providing inputs first, you'll see the **Almost There - Add Inputs First** screen prompting you to add them. {% endhint %} {% endstep %} {% step %} #### **Run** Click on the ▶️ button in the top-right to execute your workflow. After the run completes, you can: * **Review** the outputs * **Back to edit** the automation if needed * **Run again** to re-execute * **Publish** the draft to turn it into an automation * **Chat** with the **Run Assistant** for further questions or clarifications {% endstep %} {% endstepper %} ## Triggers Webhook and email triggers are configured from the draft editor. Click Inputs & Triggers in the right panel to open the trigger configuration dialog. ### Webhook Trigger A webhook trigger starts a run when an external system sends an event. This is useful for connecting Kognitos to other tools, CI/CD pipelines, or custom applications.
{% stepper %} {% step %} **Select an integration** Choose the integration that will send the webhook event. {% endstep %} {% step %} **Select a connection** Pick the connection to use for this integration. {% endstep %} {% step %} **Select an event** Choose the specific event that should trigger the automation. {% endstep %} {% step %} **Save** Click Save Trigger to activate. The automation will run whenever the selected event fires. {% endstep %} {% endstepper %} ### Email Trigger An email trigger starts a run whenever an email is received at a unique address generated by Kognitos. The email content and attachments are passed to the automation.
{% stepper %} {% step %} **Copy the mailbox address** Kognitos generates a unique email address for this automation (e.g., `automation-abc123@us-1.kognitos.com`). Copy it and use it as a forwarding destination or share it with the people or systems that should trigger runs. {% endstep %} {% step %} **Configure email filters (optional)** Expand **Email Filters** to restrict which emails trigger a run. You can filter by sender address, CC address, or subject line keywords.
{% endstep %} {% step %} **Save** Click Save Trigger to activate. Any email matching your filters will start a new run. {% endstep %} {% endstepper %} ## Publishing When your draft is working as intended, you can publish it to promote it to an automation. An **automation** is the locked version of a draft that can be executed repeatedly and reliably. Once published, the workflow is moved from **Drafts → Automations**. You can always return to edit it by selecting "Open in Drafts" from the Automation. ### Versioning Publishing a draft creates a **new major version** (v1, v2, v3, etc.) of your workflow. To make any updates, you'll need to edit the draft again and publish a new version. ## Best Practices The following tips can help you build drafts more efficiently and get more reliable results. ### 1. Work Incrementally Instead of asking Kognitos to do everything at once, build and verify in small steps.
How to Work Incrementally For example, instead of asking Kognitos: > "Extract all the fields from this page." Start with a few fields and make sure they're correct before moving on: > "Extract the first five fields from this page." When you work in small batches, a mistake is easier to spot and fix: > "The vendor name is incorrect. Use the one in the header, not the footer."
### 2. Be Specific Vague instructions can lead to unintended behavior. Tell Kognitos what you want the automation to produce or how it should decide, not just what to do in general.
How to Be More Specific Instead of: > "Validate the totals." Try: > "The total amount should equal the sum of all line items. Flag any invoice where it doesn't match." The more precise you are, the less back-and-forth is needed to produce a draft.
## Frequently Asked Questions
What does "Neurosymbolizing..." mean? Neurosymbolizing..." appears while Kognitos is processing your instructions and converting them into executable automation steps. The term combines "neuro" (neural networks/AI) with "symbolic" (logical rules and structures), reflecting how Kognitos blends natural language understanding with structured workflow logic.
Can I work on multiple drafts at once? Yes. You can have as many drafts in progress as you need. Each one is independent.
What happens if I close a draft before finishing? Your work is automatically saved. Just open the draft again from the Drafts list to continue where you left off.
Can I go back to a draft after publishing? Yes. New changes will create a new version of the automation.
Why can't I publish my draft? The publish option will be disabled if Kognitos needs more information from you to complete the workflow. Open the draft to continue the conversation and provide any missing details; the publish option will then become available.
# Automations Manage published automations, monitor runs, configure triggers, and track performance. ## Overview **Automations** are your published, production-ready workflows in Kognitos. When you build, test, and publish a draft, it becomes an automation. Think of the relationship like this: * **Drafts** are your workspace for building, editing, and testing workflows * **Automations** are the published versions actively running your operations Each time you publish a draft, Kognitos creates a new major version of the automation (v1.0, v2.0, v3.0). Published versions are locked and repeatable. To make changes, click Edit as Draft, edit, and publish again. ## Dashboard Access **Automations** from the left navigation menu. The dashboard shows workflow activity and health across your workspace.
### Runs Chart The **Runs** chart displays total automation executions over time. Toggle between **Last 7 days** (default), **Last 30 days**, or **Last 3 months** to adjust the view. ### Metrics Three cards summarize recent activity: * **Runs this week** -- total runs executed in the past 7 days * **Exceptions this week** -- total exceptions raised in the past 7 days * **Runs all time** -- total runs executed in this workspace since creation ### My Automations Below the metrics, you'll see cards for each automation in your workspace. Each card shows the automation name, description, last updated date, successful run count, and pending exception count. Use the search bar to find automations by name. Click any card to open the automation detail view. Click ⋮ on a card for additional options. ## Automation Detail View Click an automation card to see its full detail view. This page is where you monitor runs, configure triggers, and manage the automation.
### Actions From the detail view, you can: * Run -- start a new run manually * Edit as Draft -- open the automation's draft to make changes (publish again to update) * Diagram -- view a visual diagram of the automation's workflow * Document -- view the automation's execution steps as a document * ⋮ -- access additional options like rename, delete, copy, or open in Drafts ### Runs The **Runs** section lists all executions for this automation. Filter by status, date range, or trigger type. Each row shows: | Column | Description | | --------------- | -------------------------------------------------------- | | **Date & time** | When the run started and its duration | | **Trigger** | How the run was initiated (Manual, Email, Webhook) | | **Version** | Which published version was used (v1.0, v2.0, etc.) | | **Status** | Current state: Completed, Processing, Waiting, or Failed | | **Inputs** | The input values provided for this run | Click View run to see the full details for a run, including outputs and any exceptions encountered. #### Archiving Runs You can **archive** completed runs to keep your run history focused on active work. To archive a run, click ⋮ on the run row and select Archive. Archived runs are removed from the default list but can still be viewed by applying the **Archived** filter. {% hint style="info" %} Archiving a run does not delete it. You can access archived runs at any time using the status filter on the Runs list. {% endhint %} #### Run Statuses | Status | Meaning | | -------------- | -------------------------------------------- | | **Completed** | Run finished successfully | | **Processing** | Run is actively executing | | **Waiting** | Run is paused, waiting for input or guidance | | **Failed** | Run encountered an unrecoverable error | {% hint style="info" %} Runs with a **Waiting** status need attention. Open the run to provide guidance, or visit the [Guidance Center](/guides/platform/guidance-center) to manage exceptions across all automations. {% endhint %} ### Troubleshooting Guide The **Troubleshooting Guide** shows saved guidance for this automation. When a known exception recurs, Kognitos checks the guide and applies the resolution automatically. See [Troubleshooting Guide](/guides/platform/automations/troubleshooting-guide) for full details. ## Running an Automation You can start a run in several ways: * **Manually** -- click Run from the detail view * **On a schedule** -- configure a schedule to run automatically (automations without inputs only) * **From an email** -- set up an email trigger so incoming messages start a run * **Via webhook** -- configure a webhook trigger so external systems can start a run * **Through the API** -- invoke the automation programmatically using the [REST API](/guides/api-reference/api-reference) ### Inputs and Triggers Configure inputs and triggers from the [Document](/guides/platform/automations/automation-document) view by clicking Inputs & Triggers in the right panel. See [Document](/guides/platform/automations/automation-document) for details on setting up manual inputs, schedule triggers, and more. ## Versioning Each time you publish a draft, Kognitos creates a new major version of the automation. Versions are numbered sequentially (v1.0, v2.0, v3.0). * New runs always use the latest published version * In-progress runs continue on the version they started with * Previous versions are preserved in the version history {% hint style="info" %} To update a published automation, click Edit as Draft, make your changes, and publish again. This creates a new version without disrupting any runs in progress. {% endhint %} ## Frequently Asked Questions
How do I see which version an automation is on? The current version number is displayed in the automation detail view. The run history also shows which version each run used.
What happens to runs if I publish a new version? Runs already in progress continue on the version they started with. Only new runs use the latest version.
Can I schedule an automation that has inputs? No. Schedule triggers are only available for automations without required inputs. You can still use [webhook and email triggers](/guides/platform/drafts#triggers), which pass their data as inputs automatically.
# Document View execution steps, configure inputs, and set up schedule triggers from the Document view. The **Document** view shows a structured summary of your automation, including its overview, execution steps, and input/trigger configuration. Access it by clicking Document from the automation detail view. ## Inputs and Triggers Click Inputs & Triggers in the right panel to configure how the automation receives data and when it runs. **Automations with inputs** show the **Add Inputs** dialog with two modes: * Add Manually -- provide input values each time you run the automation * Add Schedule -- run on a recurring schedule (disabled when the automation has required inputs)
{% hint style="warning" %} Automations that require inputs cannot be scheduled. To use a schedule trigger, the automation must have no required input fields. {% endhint %} **Automations without inputs** show the **Triggers** dialog where you can add a schedule trigger.
### Schedule Trigger A schedule trigger runs the automation automatically on a recurring basis. Set the frequency (every N days, weeks, or months), select which days, choose a start time and timezone. Presets like **Every 5 mins**, **Hourly**, **Daily**, and **Every Weekday** are available for common schedules.
### Webhook and Email Triggers Webhook and email triggers are configured from the draft editor. See [Drafts](/guides/platform/drafts#triggers) for setup instructions. # Troubleshooting Guide Learn how to review and manage guidance that auto-applies to future runs. ## Overview The **Troubleshooting Guide** helps your automations learn from past exceptions and handle them automatically in future runs. When you resolve an issue, save the solution as **guidance** so Kognitos can fix the same problem on its own next time.
## Understanding Guidance The Troubleshooting Guide teaches your automations how to handle errors independently. When an exception occurs, Kognitos checks the guide for resolution instructions. If they exist, it applies them automatically. If they don't, it pauses to ask for help. #### What are Exceptions? **Exceptions** are issues that prevent an automation from completing its task. They occur when Kognitos encounters an unexpected condition, such as: * Missing or invalid data * Failed integrations or connections * Scenarios it hasn't been taught to handle #### What is Guidance? **Guidance** defines how an automation should respond to a specific exception. It consists of saved resolution steps and instructions associated with that exception. When the same issue recurs, the automation applies the guidance without manual intervention. #### Exception Classification Kognitos automatically classifies exceptions into types - such as system errors, configuration errors, value errors, and validation errors - so your guidance can target the right category. The classification engine is continuously improved to ensure exceptions are grouped accurately, helping you write guidance that applies reliably. #### Why Guidance Matters A well-developed Troubleshooting Guide makes your automations increasingly self-sufficient. Instead of stopping every time a familiar issue occurs, Kognitos resolves it automatically. This reduces downtime, accelerates workflows, and enables your team to focus on complex work rather than repetitive troubleshooting. ## Dashboard Access the **Troubleshooting Guide** from the left navigation menu. The main dashboard shows how your automated guidance performs across automations; use it to monitor auto-resolution rates and identify performance trends. ### Metrics The chart shows how often guidance is automatically applied over time. Use the time selector to view activity for the last **7 days** *(default)*, **30 days**, or **3 months**.
Below the chart, these metrics summarize how your guidance is performing:
MetricDescription
Guidance (all time)Total number of times guidance has been auto-applied across all runs.
RunsNumber of automations executed during the selected time range.
Exceptions auto-resolvedPercentage of exceptions handled automatically without manual intervention. Higher values indicate that guidance rules are effectively preventing disruptions and keeping automations running smoothly.
## Entries Your guidance entries are organized by automation in the left sidebar. Use the search bar to find specific guidance across all your automations. Click any entry to view its full details.
### Details Here's what you'll find in each entry: #### Root Cause Describes the specific issue that triggered this guidance. #### **Guidance** Defines the resolution steps that are automatically applied when the same situation occurs again. This determines how the automation responds when it encounters this issue. #### Created Shows who created the guidance and when it was created.
### Applied to Runs Each row represents a specific run where this guidance was applied. The table shows: * **Start time**: When the automation run began * **Applied at**: When the guidance was applied during that run * **Trigger**: How the run was initiated *(Scheduled, Manual, etc.)* * **Status**: Current state of the run *(Completed, Processing, Waiting, etc.)* * **Inputs**: Number of input items processed in this run * **Record files**: Number of records or files involved Click the filter icon next to any column header to narrow the results, or click **View exception** to see the full context for that specific run.
### Deleting Guidance To delete guidance from the Troubleshooting Guide, click on the three-dot menu in the top right corner and select **Delete Guidance**. Deleting an entry removes it from your Troubleshooting Guide, but doesn't affect past runs where it was applied. This is useful when guidance is no longer needed or the resolution steps are outdated.
## Review Guidances Kognitos identifies patterns in how you resolve exceptions and suggests adding them to your Troubleshooting Guide. When guidance suggestions are available, you'll be prompted to review them. Click **Show more** on any item to expand the full guidance text and see all the resolution details.
### Actions Review each suggestion and take action: * Click **Add to Guide** to save the guidance. It will auto-apply the next time this exception occurs. * Click **Discard** if the guidance isn't relevant. After reviewing all suggestions, close the panel. Accepted guidance entries will be added to your Troubleshooting Guide and begin auto-applying to future runs. ## Frequently Asked Questions
How does guidance get created? Guidance is created when you or a team member resolves an exception and chooses to save the resolution steps. Kognitos may also suggest guidance based on patterns it identifies in how you resolve similar exceptions.
Will guidance apply to all my automations? Each guidance entry is specific to the automation where it was created. If you encounter the same issue across multiple automations, you'll need to create guidance for each one separately.
What happens if guidance fails to resolve an exception? If guidance can't resolve an exception, the run will pause and wait for manual intervention. You can then review what happened, adjust the guidance, or resolve the exception manually.
What's the difference between "Root Cause" and "Guidance"? The **root cause** explains what triggered the exception - the problem your automation encountered. **Guidance** contains the specific steps your automation will take to fix that problem next time it occurs.
# Guidance Center Learn how to provide guidance to automations in the Guidance Center. ## Overview When an automation requires additional context or clarification to proceed, it raises an exception. An **exception** is an error or unexpected condition that prevents the automation from completing successfully. Exceptions are resolved through **guidance** - input provided to the system on how to proceed. Using the **Guidance Center**, you can quickly provide guidance across automations to keep them running smoothly.
## Exceptions **Exceptions** are issues that prevent an automation from completing successfully. They occur when Kognitos encounters an unexpected condition, such as missing or invalid data, failed integrations or connections, and scenarios it hasn't been taught to handle yet. ### Types Exceptions are grouped by the following **types**:
  1. System Errors
Issues related to the Kognitos platform or internal processes. These are typically resolved by the Kognitos engineering team, and you'll be notified when they're fixed.
  1. Configuration Errors

Issues with missing credentials, permissions, or integration settings that prevent your automation from accessing external systems.

Example: Missing API key for an integration; authentication credentials have expired.

  1. Value Errors

Missing or unclear data that prevents the automation from proceeding.

Example: A required field like "Invoice Number" is missing from a document, or a value appears in an unexpected format.

  1. Validation Errors

Issues where the automation needs confirmation that a condition or business rule has been met. Kognitos automatically classifies validation-related exceptions into this group for faster triage.

Example: Verifying that a contract clause meets company policy requirements, or confirming that extracted data passes a business rule check.

{% hint style="info" %} Exception classification has been improved to more accurately group validation errors, resulting in better organization of action items in the Guidance Center. {% endhint %} ## Using the Guidance Center Access the **Guidance Center** from the left navigation menu. It displays all open exceptions across your workspace, organized by automation and exception type. ### Dashboard When you open the Guidance Center, you'll see a summary dashboard:
#### Metrics The dashboard displays the following metrics to help you monitor automation health:
MetricDescription
Auto-completion (STP)Percentage of runs that completed without manual intervention.
Runs Need ActionNumber of runs currently paused and waiting for guidance.
Total CompletionOverall success rate across all automation runs.
Runs This WeekNumber of automation runs in the current week.
Exception RatePercentage of runs that raised exceptions.
MTTR (Mean Time to Resolution)Average time it takes to resolve exceptions.
Run Status

A visual chart that shows your automation performance over time, color-coded by resolution type:

  • Auto-completion: Runs completed without manual intervention.
  • Manually resolved: Runs that required your input to complete.
  • Action needed: Runs are currently waiting for your action.
### Action Items An **action item** is a task created when one or more runs are affected by the same exception. The Guidance Center groups these runs by exception type, allowing you to review and resolve the issues in bulk, rather than one run at a time. Each action item shows: * **Name:** The name of the issue that occurred *(Missing Values, User System Error, etc.)* * **Priority:** The severity of the automation exception * **Run count:** How many runs is this exception affecting * **Automations:** A list of automations that raised the exception
Selecting an action item lets you view the affected runs, review details, and provide guidance in bulk. Click on **Start review** to review the impacted runs and provide guidance.
### System Issues **System Issues** are internal platform errors that are being handled by the Kognitos engineering team.
{% hint style="success" %} No action is required from you for system issues - Kognitos will handle them. {% endhint %} # Integrations Learn how to extend your automation functionality with integrations. ## Overview **Integrations** enable Kognitos to work with specific tools, platforms, services, or objects. Each integration provides specific [**actions**](#actions) that can extend your automation capabilities, such as "create a ticket", "extract data from a PDF", or "update a record". ## Library To see all available integrations, go to **Integrations → Explore Integrations**. Within this view, you can: * **Browse** the full catalog alphabetically * **Filter** by category *(Accounting, Business Productivity, Collaboration, etc.)* * **Search** directly by integration name Click into any integration to view more details.
## How Integrations Work An **integration** is a collection of related actions that work with specific tools, platforms, services, or objects. They can extend your automation capabilities by enabling Kognitos to interact with different systems and perform specialized tasks. Integrations serve different purposes depending on their design. Some integrations can connect to external platforms like [**Salesforce**](/guides/platform/integrations/salesforce), [**Microsoft Excel**](/guides/platform/integrations/excel), or [**SAP**](/guides/platform/integrations/sap). Other integrations, such as [**Intelligent Document Processing**](/guides/platform/integrations/idp), enable you to extract and analyze information from various document types. When you describe a task, Kognitos automatically identifies the required integrations and prompts you to connect them if they're not already available in your workspace. For example: > **Example Instruction:** > > Read invoice data from the Excel file in our shared drive, validate each invoice against our Salesforce accounts, and email a summary to . > > **What Kognitos identifies:** > > * **Google Drive** integration for file access > * **Salesforce** integration for account validation > * **Gmail** integration for sending email You can also connect integrations from the [**library**](#integrations-library) at any time. ## Connections A **connection** is a configured link between Kognitos and an external system or service. It stores authentication credentials *(such as API keys, tokens, or login details)*, environment settings, and version information that an integration needs to interact with that system. Connections are secure and reusable across multiple automations. ### Management Connections are managed separately from automations. To view, add, edit, or manage your connections: 1. Navigate to **Integrations → Connections**. 2. You'll see a list of all configured connections, including: 1. **Connection Name** 2. **Environment** *(Test or Production)* 3. **Integration Name** 4. **Integration Version Number** 5. **Authentication Method** *(Personal Access Token, Client Credentials, etc.)* 6. **Automations** 7. **Status** *(Connected or Disconnected)* 8. **Actions** *(Edit or Delete)*
This page makes it easy to monitor, update, and troubleshoot your connections in one place. ### Creating Connections Create a new connection either directly from an **Integration** or from **Connections**. {% tabs %} {% tab title="Via Integrations" %} 1. Navigate to **Integrations → Explore Integrations.** 2. Find the integration you'd like to connect, then click it. 3. On the integration details page, click **+ New Connection**. 4. Configure the connection: 1. Provide a name for the connection. 2. Check **Use same account for testing and production** to apply the same authentication details to both drafts and automations. 3. Select an authentication method, then click **Continue** to provide the credentials. 4. Finally, click **Connect**. {% endtab %} {% tab title="Via Connections" %} 1. Navigate to **Apps → Connections.** 2. Click on **+ New Connection**. 3. Select the integration you'd like to connect to from the dropdown menu. 4. Configure the connection: 1. Provide a name for the connection. 2. Check **Use same account for testing and production** to apply the same authentication details to both drafts and automations. 3. Select an authentication method, then click **Continue** to provide the credentials. 4. Finally, click **Connect**. {% endtab %} {% endtabs %} ### Multiple Connections A single integration can have **multiple connections**, each with different credentials or authentication methods. For example, you might create one GitHub connection for your personal organization and another for your company's organization. Or, you could set up separate Excel connections to access workbooks from different accounts. This flexibility allows you to switch between different connections within the same integration, depending on what your automation needs to access. ## Actions Each integration defines a set of **actions** that determine what operations you can perform, such as reading data from a spreadsheet, sending an email, or creating a record in a CRM system. For example, the **File** integration includes actions like:
Get the file's size Get the size of a file in a human-readable format.
Get the file's extension Get the extension of a file *(e.g., .pdf, .xlsx, .txt)*.
Read the file as a base64 string Read the contents of a file as a base64-encoded string.
Once an integration is configured in your workspace, its actions become available for use in your workflows. You can **combine actions** from multiple integrations to build workflows that span multiple systems. For example, you might use Excel actions to read invoice data, Salesforce actions to check customer information, and email actions to send confirmations - all within a single automation. ### Custom Actions Some integrations have **custom actions** that must be discovered and enabled before they can be used. Integrations like [SAP](/guides/platform/integrations/sap) and [Salesforce](/guides/platform/integrations/salesforce) fall into this category; their actions must be configured to control which specific services or operations are accessible within the workspace. #### Configuration To configure custom actions for a given integration: {% stepper %} {% step %} **Open the Integration** Navigate to **Integrations**, then locate and click the already-connected integration. {% hint style="warning" %} **Note:** You must have an active [connection](#connections) to the integration before you can configure custom actions. {% endhint %} {% endstep %} {% step %} **Access Configuration Menu** Click the three-dot menu **⋯** next to the connection name and select **Configure Actions**.
{% endstep %} {% step %} **Search and Enable Actions** Browse or search for the specific actions or services you need. Toggle them on to enable them for use in your workspace. For example, in SAP, you might enable services like "Obtain Service for Material Document API" or "Manage Excitations - Products."
{% endstep %} {% step %} **Save** Click **Save** to apply your configuration. Allow 1-2 minutes for the system to complete the discovery process. Once complete, these actions will become available in your draft conversations or automations. {% endstep %} {% endstepper %} ## Versions Integrations are **versioned** to ensure stability and reliability. The latest version is displayed under Version Information. You can choose to upgrade at your own pace, gaining access to enhancements without disrupting your workflows. # Airtable Overview of the Airtable integration. {% hint style="info" %} The following documentation is for **Airtable v2.0.0**. {% endhint %} ## Overview Airtable is a database platform that works like a spreadsheet. This integration allows you to create records, sync data, and manage workflows in your Airtable bases. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Airtable** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using personal access token Connects using a Personal Access Token from Airtable. | Label | Description | Type | | --------------------- | -------------------------- | ----------- | | personal access token | The Personal Access Token. | `sensitive` | ## Actions The following actions are available in the **Airtable** integration: ### 1. Create a record in a table Creates a new record in a table ### 2. Get some base's tables Gets a list of all tables from a specific base ### 3. Get some bases Gets a list of all bases ### 4. Get some table's records Gets a list of all records from a specific table ## Concepts ### Airtable table Represents an Airtable table. | Field Name | Description | Type | | ------------- | -------------------------------------------------------- | ---------------- | | `id` | The unique identifier of the table. | `text` | | `base_id` | The unique identifier of the base containing this table. | `text` | | `name` | The name of the table. | `optional[text]` | | `description` | Optional description of the table. | `optional[text]` | ### Airtable record Represents an Airtable record. A record is a row of a table. | Field Name | Description | Type | | ---------- | --------------------------------------------------- | ------ | | `id` | The unique identifier of the record. | `text` | | `fields` | Dictionary containing the field data of the record. | `json` | ### Airtable base Represents an Airtable base. A base is a collection of tables. | Field Name | Description | Type | | ---------- | ---------------------------------- | ---------------- | | `id` | The unique identifier of the base. | `text` | | `name` | The name of the base. | `optional[text]` | # Amazon Selling Partner Overview of the Amazon Selling Partner integration. {% hint style="info" %} The following documentation is for **Amazon Selling Partner v2.0.1**. {% endhint %} ## Overview Amazon Selling Partner connects you to Amazon's marketplace to automate order retrieval and processing. This integration allows you to pull order data from your Amazon seller account and integrate it seamlessly into your workflows. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Amazon Selling Partner** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Refresh Token, Client ID and Client Secret Connect to Amazon Selling Partner API using LWA OAuth credentials. | Label | Description | Type | | ------------- | -------------------------------------------------------- | ----------- | | Refresh Token | LWA refresh token from Seller Central | `sensitive` | | Client ID | LWA client ID (starts with amzn1.application-oa2-client) | `text` | | Client Secret | LWA client secret | `sensitive` | ## Actions The following actions are available in the **Amazon Selling Partner** integration: ### 1. Retrieve orders Retrieve orders from Amazon Selling Partner API. ### 2. Retrieve an order from amazon selling partner Retrieve order details from Amazon Selling Partner API. ## Concepts ### Amazon order Amazon Selling Partner order information. | Field Name | Description | Type | | ---------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------ | | `amazon_order_id` | The unique Amazon order identifier. | `text` | | `order_status` | The current status of the order. | `text` | | `purchase_date` | The date when the order was purchased. | `text` | | `last_update_date` | The date when the order was last updated. | `text` | | `marketplace_id` | The Amazon marketplace identifier. | `optional[text]` | | `fulfillment_channel` | The fulfillment channel (e.g., MFN, AFN). | `optional[text]` | | `order_type` | The type of order. | `optional[text]` | | `shipment_service_level_category` | The shipment service level category. | `optional[text]` | | `earliest_ship_date` | The earliest ship date. | `optional[text]` | | `latest_ship_date` | The latest ship date. | `optional[text]` | | `earliest_delivery_date` | The earliest delivery date. | `optional[text]` | | `latest_delivery_date` | The latest delivery date. | `optional[text]` | | [`shipping_address`](#shipping_address-amazon-order) | The shipping address. | `optional[json]` | | [`default_ship_from_location_address`](#default_ship_from_location_address-amazon-order) | The default ship from location address. | `optional[json]` | | `number_of_items_shipped` | The number of items shipped. | `optional[number]` | | `number_of_items_unshipped` | The number of items unshipped. | `optional[number]` | | `payment_method` | The payment method. | `optional[text]` | | `payment_method_details` | List of payment method details. | `optional[list of text]` | | [`buyer_info`](#buyer_info-amazon-order) | Buyer information. | `optional[json]` | | `is_business_order` | Whether this is a business order. | `optional[boolean]` | | `is_prime` | Whether this is a Prime order. | `optional[boolean]` | | `is_global_express_enabled` | Whether global express is enabled. | `optional[boolean]` | | `is_premium_order` | Whether this is a premium order. | `optional[boolean]` | | `is_sold_by_ab` | Whether sold by Amazon Business. | `optional[boolean]` | | `is_iba` | Whether this is an IBA order. | `optional[boolean]` | | `is_ispu` | Whether this is an ISPU order. | `optional[boolean]` | | `is_access_point_order` | Whether this is an access point order. | `optional[boolean]` | | [`fulfillment_instruction`](#fulfillment_instruction-amazon-order) | Fulfillment instructions. | `optional[json]` | | [`automated_shipping_settings`](#automated_shipping_settings-amazon-order) | Automated shipping settings. | `optional[json]` | | `sales_channel` | The sales channel. | `optional[text]` | | `order_channel` | The order channel. | `optional[text]` | | `ship_service_level` | The ship service level. | `optional[text]` | | `order_total` | The order total amount. | `optional[json]` | | `payment_execution_detail` | Payment execution details. | `optional[list of json]` | #### Concept attribute specifications **shipping\_address (amazon order)** | Name | Type | | ----------------- | ---------------- | | `name` | `optional[text]` | | `address_line1` | `optional[text]` | | `address_line2` | `optional[text]` | | `address_line3` | `optional[text]` | | `city` | `optional[text]` | | `county` | `optional[text]` | | `district` | `optional[text]` | | `state_or_region` | `optional[text]` | | `municipality` | `optional[text]` | | `postal_code` | `optional[text]` | | `country_code` | `optional[text]` | | `phone` | `optional[text]` | | `address_type` | `optional[text]` | **default\_ship\_from\_location\_address (amazon order)** | Name | Type | | ----------------- | ---------------- | | `name` | `optional[text]` | | `address_line1` | `optional[text]` | | `address_line2` | `optional[text]` | | `address_line3` | `optional[text]` | | `city` | `optional[text]` | | `county` | `optional[text]` | | `district` | `optional[text]` | | `state_or_region` | `optional[text]` | | `municipality` | `optional[text]` | | `postal_code` | `optional[text]` | | `country_code` | `optional[text]` | | `phone` | `optional[text]` | | `address_type` | `optional[text]` | **buyer\_info (amazon order)** | Name | Type | | ----------------------- | ---------------- | | `buyer_email` | `optional[text]` | | `buyer_name` | `optional[text]` | | `buyer_county` | `optional[text]` | | `buyer_tax_info` | `optional[json]` | | `purchase_order_number` | `optional[text]` | **fulfillment\_instruction (amazon order)** | Name | Type | | ------------------------------ | ---------------- | | `fulfillment_supply_source_id` | `optional[text]` | **automated\_shipping\_settings (amazon order)** | Name | Type | | --------------------------------- | ------------------- | | `has_automated_shipping_settings` | `optional[boolean]` | | `automated_carrier` | `optional[text]` | | `automated_ship_method` | `optional[text]` | # Anthropic Overview of the Anthropic integration. {% hint style="info" %} The following documentation is for **Anthropic v1.1.4**. {% endhint %} ## Overview This integration provides LLM functionality by connecting to the Anthropic API, enabling you to send prompts and receive AI-generated responses for natural language processing workflows. ### Setup The following integrations need to be connected to your Kognitos workspace: * **Anthropic** #### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} #### Credentials **1. Anthropic API Key** Follow these steps to obtain your Anthropic API key: {% stepper %} {% step %} **Log in to the Anthropic Console** Go to the [**Anthropic Console**](https://console.anthropic.com) and log in with your credentials. {% endstep %} {% step %} **Navigate to API Keys** Go to **Settings** > **API Keys**. Then click **+ Create Key** in the top right. {% endstep %} {% step %} **Configuration** Select a workspace and give your key a descriptive name (e.g., "Development Key" or "Production App"). Then, click **Add** to generate your API key. {% endstep %} {% step %} **Copy and Store Your Key** Copy your API key immediately and store it securely. You won't be able to view it again after closing the dialog. {% endstep %} {% endstepper %} ### Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using API Key Connect using an API key. | Label | Description | Type | | ------- | ------------------------------- | ----------- | | API Key | The API key for authentication. | `sensitive` | ### Actions The following actions are available in the **Anthropic** integration: #### 1. Prompt anthropic Send a prompt to the Anthropic Claude LLM and get a response. # Asana Overview of the Asana integration. {% hint style="info" %} The following documentation is for **Asana v1.1.1**. {% endhint %} ## Overview Asana is a project management platform for organizing work, tracking tasks, and coordinating teams. This integration lets you create and update tasks, assign work, add comments, and retrieve projects, sections, and users from Asana. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Asana** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. ### Sign in with Asana To connect to the **Asana** integration, click on Sign in with Asana. This redirects you to Asana so you can sign in and authorize the connection. ### OAuth Authorization Code Connect to Asana with your own OAuth client. | Label | Description | Type | | ------------- | ----------------------- | ----------- | | Client ID | OAuth client identifier | `text` | | Client Secret | OAuth client secret | `sensitive` | ### API Key Connect to Asana with a Personal Access Token. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------- | | Personal Access Token | The Asana Personal Access Token (PAT). Found under **My Settings** → **Apps** → **Personal Access Tokens** in Asana. | `sensitive` | ## Actions The following actions are available in the **Asana** integration: ### 1. Add a comment to a task Add a comment to an existing Asana task. ### 2. Assign a task to a user Assign an Asana task to a user. ### 3. Complete a task Mark an Asana task as complete. ### 4. Create a task in a project Create a new task in an Asana project. ### 5. Delete a task Delete an Asana task. ### 6. Get comments from a task Retrieve comments for a task. ### 7. Get projects Retrieve projects from Asana. ### 8. Get sections from a project Retrieve sections from an Asana project. ### 9. Get tasks from a project Retrieve tasks from an Asana project. ### 10. Get users Retrieve users from Asana. ### 11. Update a task Update an existing Asana task. # Aspire Overview of the Aspire integration. {% hint style="info" %} The following documentation is for **Aspire v1.1.1**. {% endhint %} ## Overview An integration with aspire ## Setup The following integrations need to be connected to your Kognitos workspace: * **Aspire** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Base URL, Client ID and Client Secret Connects to the Aspire API using client credentials. | Label | Description | Type | | ------------- | --------------------------------------------------------------------------- | ----------- | | Base URL | The base URL of the Aspire API (e.g. ""). | `text` | | Client ID | The client ID for the Aspire API. | `text` | | Client Secret | The client secret for the Aspire API. | `sensitive` | ## Actions The following actions are available in the **Aspire** integration: ### 1. Create an opportunity for a property Create an opportunity in Aspire for a given property. ### 2. Get the branches Fetch the list of branches from Aspire. ### 3. Get the catalog items Fetch the list of catalog items from Aspire. ### 4. Get the opportunities Fetch the list of opportunities from Aspire. ### 5. Get the opportunity statuses Fetch the list of opportunity statuses from Aspire. ### 6. Get the properties Fetch the list of properties from Aspire. ### 7. Get the regions Fetch the list of regions from Aspire. ### 8. Update a catalog item Update an existing catalog item in Aspire. ## Concepts ### Aspire opportunity An opportunity in Aspire | Field Name | Description | Type | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | `opportunity_name` | The name of the opportunity. | `text` | | `opportunity_id` | The unique identifier (read-only, assigned by API). | `optional[number]` | | `opportunity_type` | The type (e.g. "Contract", "Work Order"). | `optional[text]` | | `opportunity_status` | The current status (read-only). | `optional[text]` | | `opportunity_status_id` | The status ID. Use `get_opportunity_statuses()` to discover valid IDs (e.g. the "1-New" status). | `optional[number]` | | `property_id` | The property to associate. Use `get_properties()` to list. | `optional[number]` | | `property_name` | The associated property name (read-only). | `optional[text]` | | `branch_name` | The branch name (read-only). | `optional[text]` | | `division_id` | The division ID. Typically copied from a template opportunity or chosen to match the property's branch. | `optional[number]` | | `division_name` | The division name (read-only). | `optional[text]` | | `sales_rep_id` | The sales-rep contact ID. Use the `AccountOwnerContactID` from the target property, or look up a known sales-rep from an existing opportunity's `SalesRepContactID`. **Note:** the API write field is `SalesRepID`; the read field is `SalesRepContactID`. | `optional[number]` | | `sales_rep` | The sales rep contact name (read-only). | `optional[text]` | | `template_opportunity_id` | An existing opportunity whose services / line items will be copied into the new one. Use `get_opportunities()` with a filter to find a suitable template. | `optional[number]` | | `start_date` | The start date. | `optional[datetime]` | | `end_date` | The end date. | `optional[datetime]` | | `estimated_dollars` | The estimated dollar amount (read-only). | `optional[number]` | | `opportunity_number` | The opportunity number (read-only). | `optional[number]` | ### Aspire branch A branch in Aspire.Branches belong to regions and are useful for mapping properties to their region. Use `get_branches()` alongside `get_regions()` to build the full region-to-branch hierarchy. | Field Name | Description | Type | | ------------------------- | --------------------------------------------------- | ------------------- | | `branch_id` | The unique identifier for the branch. | `number` | | `branch_name` | The name of the branch. | `text` | | `active` | Whether the branch is active. | `optional[boolean]` | | `internal_property_id` | The ID of the internal property for this branch. | `optional[number]` | | `internal_property_name` | The name of the internal property. | `optional[text]` | | `catalog_price_list_name` | The catalog price list associated with this branch. | `optional[text]` | | `branch_address_id` | The ID of the branch address. | `optional[number]` | | `region_id` | The ID of the region this branch belongs to. | `optional[number]` | | `region_name` | The name of the region this branch belongs to. | `optional[text]` | ### Aspire catalog item A catalog item in Aspire | Field Name | Description | Type | | --------------------------- | ------------------------------------------- | -------------------- | | `catalog_item_id` | The unique identifier for the catalog item. | `number` | | `item_name` | The name of the item. | `text` | | `catalog_item_category_id` | The category ID of the catalog item. | `optional[number]` | | `item_type` | The type of the item. | `optional[text]` | | `item_description` | The description of the item. | `optional[text]` | | `item_code` | The code of the item. | `optional[text]` | | `item_cost` | The cost of the item. | `optional[number]` | | `purchase_unit_cost` | The purchase unit cost. | `optional[number]` | | `purchase_unit_type_name` | The purchase unit type name. | `optional[text]` | | `allocation_unit_type_name` | The allocation unit type name. | `optional[text]` | | `available_to_bid` | Whether the item is available to bid. | `optional[boolean]` | | `active` | Whether the item is active. | `optional[boolean]` | | `catalog_name` | The name of the catalog. | `optional[text]` | | `last_updated` | The last updated date and time. | `optional[datetime]` | ### Aspire opportunity status An opportunity status in Aspire | Field Name | Description | Type | | ----------------------- | ------------------------------------------------- | --------- | | `opportunity_status_id` | The unique identifier for the opportunity status. | `number` | | `status` | The status label. | `text` | | `status_name` | The display name of the status. | `text` | | `stage` | The stage label. | `text` | | `stage_name` | The display name of the stage. | `text` | | `active` | Whether the status is active. | `boolean` | | `required` | Whether the status is required. | `boolean` | ### Aspire property A property in Aspire | Field Name | Description | Type | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------ | | `property_id` | The unique identifier for the property. | `number` | | `property_name` | The name of the property. | `text` | | `property_status` | The status of the property. | `optional[text]` | | `branch_id` | The ID of the branch this property belongs to. | `optional[number]` | | `branch_name` | The branch this property belongs to. | `optional[text]` | | `branch_code` | The short code for the branch. | `optional[text]` | | `account_owner_contact_id` | The account owner contact ID. Can be used as `sales_rep_id` when creating opportunities. | `optional[number]` | | `account_owner` | The account owner contact name. | `optional[text]` | | `address_line_1` | The first line of the property address. | `optional[text]` | | `city` | The city of the property. | `optional[text]` | | `state` | The state/province code. | `optional[text]` | | `zip_code` | The zip code of the property. | `optional[text]` | | `active` | Whether the property is active. | `optional[boolean]` | | `modified_date` | The last modified date. | `optional[datetime]` | | `modified_by_user_name` | The name of the user who last modified. | `optional[text]` | | `property_type_id` | The property type ID. | `optional[number]` | | `property_type` | The property type name. | `optional[text]` | | [`property_takeoff_items`](#aspire-property-takeoff-item) | Measured quantities for this property (e.g. total bed area, snow lots). | `optional[list of aspire property takeoff item]` | ### Aspire property takeoff item A takeoff item associated with a property in Aspire.Takeoff items capture measured quantities for a property (e.g. total bed area, number of snow lots). | Field Name | Description | Type | | -------------------------- | ------------------------------------------- | ------------------ | | `property_takeoff_item_id` | The unique identifier for this association. | `number` | | `takeoff_item_id` | The ID of the takeoff item definition. | `number` | | `takeoff_item_name` | The name of the takeoff item. | `text` | | `takeoff_item_value` | The measured value. | `optional[number]` | ### Aspire region A region in Aspire | Field Name | Description | Type | | ------------------ | ------------------------------------- | ---------------- | | `region_id` | The unique identifier for the region. | `number` | | `region_name` | The name of the region. | `text` | | `legal_name` | The legal name of the region. | `optional[text]` | | `address_line_1` | The first line of the region address. | `optional[text]` | | `address_city` | The city of the region. | `optional[text]` | | `address_state` | The state/province code. | `optional[text]` | | `address_zip_code` | The zip code of the region. | `optional[text]` | | `manager_name` | The manager of the region. | `optional[text]` | | `district_name` | The district the region belongs to. | `optional[text]` | | `phone_number` | The phone number of the region. | `optional[text]` | # Azure Blob Storage Overview of the Azure Blob Storage integration. {% hint style="info" %} The following documentation is for **Azure Blob Storage v1.3.4**. {% endhint %} ## Overview Azure Blob Storage provides massively scalable object storage for unstructured data in the cloud. This integration enables automated file management, data archiving, and cloud storage workflows within Microsoft Azure. Leverage enterprise-grade cloud storage for secure and scalable data operations. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Azure Blob Storage** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Azure account name and Azure account Key Connect to a Blob Storage account using the provided account key. | Label | Description | Type | | ------------------ | ---------------------- | ----------- | | Azure account name | The Azure account name | `text` | | Azure account Key | The Azure account Key | `sensitive` | ### Connect using Azure Account Name, SAS Token and Container Name Connect to an API using the provided API key. | Label | Description | Type | | ------------------ | ---------------------- | ----------- | | Azure Account Name | The Azure account name | `text` | | SAS Token | The SAS token | `sensitive` | | Container Name | The container name | `text` | ## Actions The following actions are available in the **Azure Blob Storage** integration: ### 1. Copy an item to a folder Copy a file or folder to a specified destination folder within the container. ### 2. Create a folder in another folder Create a new subfolder inside an existing folder. ### 3. Delete an item Delete a file or folder from the storage container. ### 4. Download a file Download a file from Azure Blob Storage to use in your automation. ### 5. Get a folder at a path Get a reference to a folder at a specific path within the container. ### 6. Get a root folder from a container Get a reference to the root folder of a storage container. ### 7. Get some folder's items List the files and subfolders contained within a folder. ### 8. Move an item to a folder Move a file or folder to a different destination folder within the container. ### 9. Rename an item to a name Rename a file or folder to a new name. ### 10. Sign a blob Generate a signed URL for a blob, providing temporary access to the resource. ### 11. Upload a file to a folder Upload a file to a specified folder in Azure Blob Storage. ## Concepts ### Azure file reference Represents a reference to a file in an Azure Storage. | Field Name | Description | Type | | ---------------- | -------------------------------------------------------------------------------------- | ---------------- | | `container_name` | The name of the container. | `text` | | `blob_name` | The full path of the file within the container, including the file name and extension. | `text` | | `account_name` | The name of the account. | `optional[text]` | | `etag` | Entity tag. | `optional[text]` | | `sas_token` | SAS token. | `optional[text]` | ### Azure folder reference Represents a reference to a folder in an Azure Storage | Field Name | Description | Type | | ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------- | | `container_name` | The name of the container. | `text` | | `path` | The path of the folder within the container. Should end with a trailing slash ('/') to indicate it's a folder. | `text` | | `account_name` | The name of the account. | `optional[text]` | | `etag` | Entity tag | `optional[text]` | | `sas_token` | SAS token. | `optional[text]` | # Azure Key Vault Overview of the Azure Key Vault integration. {% hint style="info" %} The following documentation is for **Azure Key Vault v1.3.4**. {% endhint %} ## Overview Azure Key Vault securely stores and manages cryptographic keys, secrets, and certificates in the cloud. This integration enables automated secret management, key rotation, and secure credential workflows. Strengthen security posture and automate sensitive data protection in Azure environments. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Azure Key Vault** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Azure tenant ID, Azure client ID, Azure client secret and Azure subscription ID Connect to Microsoft Graph API using client credentials. | Label | Description | Type | | --------------------- | --------------------------- | ----------- | | Azure tenant ID | The Azure tenant ID | `text` | | Azure client ID | The client (application) ID | `text` | | Azure client secret | The client secret | `sensitive` | | Azure subscription ID | The Azure subscription ID | `text` | ## Actions The following actions are available in the **Azure Key Vault** integration: ### 1. Get key vaults Retrieve all Key Vaults accessible to the authenticated principal in your Azure subscription. ### 2. Get a secret from a key vault Retrieve a specific secret from a Key Vault by name. ### 3. List secrets in a key vault List all secrets stored in a specific Key Vault. ## Concepts ### Azure key vault reference Represents a reference to an Azure Key Vault. | Field Name | Description | Type | | ----------------- | ------------------------------------------------ | ---------------- | | `id` | The ID of the key vault. | `text` | | `name` | The name of the key vault. | `text` | | `url` | The URL of the key vault. | `text` | | `location` | The Azure region where the key vault is located. | `optional[text]` | | `resource_group` | The resource group containing the key vault. | `optional[text]` | | `subscription_id` | The subscription ID containing the key vault. | `optional[text]` | # Azure Service Bus Overview of the Azure Service Bus integration. {% hint style="info" %} The following documentation is for **Azure Service Bus v1.3.4**. {% endhint %} ## Overview Azure Service Bus provides reliable cloud messaging as a service (MaaS) and simple hybrid integration. This integration enables automated message queuing, publish-subscribe messaging, and enterprise messaging workflows. Enhance application reliability and enable scalable communication between distributed applications and services. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Azure Service Bus** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Connection String Connect to Azure Service Bus using connection string parameters. | Label | Description | Type | | ----------------- | --------------------------------------------------- | ----------- | | Connection String | The connection string for the Service Bus namespace | `sensitive` | ## Actions The following actions are available in the **Azure Service Bus** integration: ### 1. Receive a message from a queue Retrieve the latest message from an Azure Service Bus queue for processing in your automation. ### 2. Send a message to a queue Send a message to an Azure Service Bus queue to trigger downstream processes or communicate with other services. # Azure Translator Overview of the Azure Translator integration. {% hint style="info" %} The following documentation is for **Azure Translator v1.3.4**. {% endhint %} ## Overview Azure Translator provides AI-powered language translation services for global communication and localization. This integration enables automated text translation, language detection, and multilingual content workflows. Break down language barriers and automate international communication processes. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Azure Translator** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Azure translator instance ID and Azure translator instance key Connect to an API using the provided API key. | Label | Description | Type | | ----------------------------- | --------------------------------- | ------ | | Azure translator instance ID | The Azure translator instance ID | `text` | | Azure translator instance key | The Azure translator instance key | `text` | ## Actions The following actions are available in the **Azure Translator** integration: ### 1. Translate a document to a language Translate an entire document to a specified target language using Azure's AI-powered translation service. ## Concepts ### Azure file reference Represents a reference to a file in an Azure Storage. | Field Name | Description | Type | | ---------------- | -------------------------------------------------------------------------------------- | ---------------- | | `container_name` | The name of the container. | `text` | | `blob_name` | The full path of the file within the container, including the file name and extension. | `text` | | `account_name` | The name of the account. | `optional[text]` | | `etag` | Entity tag. | `optional[text]` | | `sas_token` | SAS token. | `optional[text]` | ### Azure folder reference Represents a reference to a folder in an Azure Storage | Field Name | Description | Type | | ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------- | | `container_name` | The name of the container. | `text` | | `path` | The path of the folder within the container. Should end with a trailing slash ('/') to indicate it's a folder. | `text` | | `account_name` | The name of the account. | `optional[text]` | | `etag` | Entity tag | `optional[text]` | | `sas_token` | SAS token. | `optional[text]` | # Basecamp Overview of the Basecamp integration. {% hint style="info" %} The following documentation is for **Basecamp v1.0.3**. {% endhint %} ## Overview Basecamp is a project management and team communication tool. This integration supports reading and writing projects, to-do lists, to-dos, messages, comments, and people through the Basecamp 4 API. After connecting via OAuth, you will be prompted to select the Basecamp account to use. The integration discovers the account automatically from your authorization. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Basecamp** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### OAuth Authorization Code Connect to Basecamp using OAuth. Provide the following from your OAuth application: | Label | Description | Type | | ------------- | ----------------------- | ----------- | | Client ID | OAuth client identifier | `text` | | Client Secret | OAuth client secret | `sensitive` | ## Actions {% hint style="info" %} The available actions for **Basecamp** are listed in the product UI on the integration page once you create a connection. {% endhint %} # Browser Overview of the Browser integration for step-by-step web automation. ## Overview The **Browser** integration lets you automate web interactions through **precise, individual actions** — navigating to a page, clicking buttons, filling forms, verifying content, and more. Each run uses: * **Live view** to watch the browser in real time. * **Agent step stream** to track what the agent is doing step-by-step. * **Restricted tools** so the agent is limited to approved browser actions (not arbitrary code execution). Use the Browser integration when you need: * **Fine-grained control** over each interaction on a web page. * **Secure credential handling** where passwords and secrets are injected without being exposed to the agent or logs. * **Verification** that specific content or values are present before continuing. * **File downloads and uploads** as part of a web workflow. * **Data extraction** from pages using AI-powered reading. For visual extraction workflows, connect **Intelligent Document Processing (IDP)**. ## How It Works Browser automation follows this workflow: 1. You describe the task in natural language. 2. The agent explores the page and authors a deterministic automation. 3. The automation is run and a verification pass checks stability. 4. You review progress in live view and the step stream. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Browser** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for **Browser** and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication The **Browser** book can be used **with or without credentials**. To automate workflows that require login or sensitive input, connect with **Browser Credentials**. Credentials are stored as named key-value pairs and injected securely at runtime. Credential values are not exposed to the agent and are not shown in your automation outputs. ### Credential key naming rules Credential **key names** (the left-hand side of each pair) must contain only: * Alphanumeric characters (`A–Z`, `a–z`, `0–9`) * Hyphens (`-`) * Underscores (`_`) Characters such as `@`, `.`, and spaces are **not allowed** in key names. {% hint style="warning" %} Do not put your actual email address (or any value containing `@`) in the key name field. The key is just a label you choose to reference the credential — the value is where the actual secret goes. {% endhint %} **Example — email-based login:** | Key | Value | | ---------------- | ----------------- | | `email_address` | `you@example.com` | | `email_password` | `your_password` | You can optionally reference credentials by key name in your prompt — for example, `"type the 'email_address' credential in the Email field"` — though the agent will also discover and use the right credential automatically. ## Getting Started A typical Browser automation follows this pattern: 1. **Provision** a browser. 2. **Navigate** to a website. 3. **Interact** with the page — click buttons, fill out forms, select options. 4. **Verify** that the expected content appeared. 5. **Extract** information if needed. 6. **Close** the browser. Describe each step in plain English in your prompt. For example: > Provision a browser. Navigate to . Type "admin" in the Username field. Type the "password" credential in the Password field. Click the Log In button. Verify that "Welcome" is visible on the page. Then close the browser. ## Best Practices * **Provision first.** Every browser interaction requires a provisioned browser, so always start by provisioning one. * **Prompt with clear intent.** Describe the business outcome first, then the key page steps. * **Be specific about elements.** Instead of "click the button," say "click the **Submit Order** button" or "type in the **Email** field." * **Use scope when elements share the same name.** If a page has two sections with a "Street" field, specify which one: "type '123 Main St' in the Street field in the **Billing Address** section." * **Use credentials for sensitive data.** Reference credentials by name rather than typing secrets directly. * **Add explicit verification steps.** Confirm expected state after key transitions (for example, "verify that 'Order confirmed' is visible"). ## Actions The following capabilities are available in the **Browser** integration: ### Lifecycle | Action | Description | | -------------------- | ---------------------------------------------------------------------------------------------- | | Provision a browser | Start a new remote browser session. Returns a live view URL you can use to watch in real time. | | Close a browser | End the browser session and release resources. | | Get downloaded files | Retrieve any files the browser downloaded during the session. | ### Navigation | Action | Description | | ----------------- | ---------------------------------------------------- | | Navigate to a URL | Open a web page in the browser. | | Go back | Navigate to the previous page in browser history. | | Go forward | Navigate to the next page in browser history. | | Scroll the page | Scroll up, down, left, or right on the current page. | ### Clicking and Hovering | Action | Description | | ---------------- | --------------------------------------------------------------- | | Click an element | Click a button, link, or other interactive element on the page. | | Hover an element | Move the cursor over an element without clicking. | | Drag an element | Drag one element to another location on the page. | ### Typing and Selection | Action | Description | | ------------------------ | ----------------------------------------------------------------------------------------------- | | Type text | Type into an input field. Can optionally press Enter after typing. | | Type a credential | Securely type a credential value (e.g., a password) into a field. Requires Browser Credentials. | | Select a dropdown option | Choose an option from a dropdown or combobox. | | Press a key | Press a keyboard key or combination (e.g., Enter, Tab, Ctrl+A). | ### Forms and File Upload | Action | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------- | | Fill a form | Fill multiple fields in a single step. | | Fill a form using credentials | Fill a form where some fields use securely stored credential values. Requires Browser Credentials. | | Upload a file | Upload a file to a file input on the page. | ### Dialogs and Tabs | Action | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Handle a dialog | Accept or dismiss the next browser dialog (alert, confirm, prompt). Must be called before the action that triggers the dialog. | | List tabs | See all open browser tabs with their titles and URLs. | | Switch tab | Switch focus to a different browser tab. | ### Waiting | Action | Description | | ---------------------- | --------------------------------------------------------------- | | Await text | Wait until specific text appears on the page (up to a timeout). | | Await a specified time | Pause for a set number of seconds. | ### Verification | Action | Description | | ---------------------------- | ------------------------------------------------------------------------- | | Verify text is visible | Confirm that specific text is visible on the page. | | Verify an element is visible | Confirm that a specific element is present and visible. | | Verify a value | Confirm that a form field contains an expected value. | | Verify a list | Confirm that all items in a list of text strings are visible on the page. | ### Observation and Extraction | Action | Description | | ------------------------- | -------------------------------------------------------------------------------------------------- | | Take a snapshot | Get a structured, text-based view of all elements on the page. Useful for inspecting page content. | | Take a screenshot | Capture a visual image of the current page. | | Extract from a screenshot | Use AI to answer a question about the visual content of the page. | | Extract from a snapshot | Use AI to answer a question about the structured content of the page. | {% hint style="info" %} Extraction actions use AI and are best suited for one-off reads. Avoid requesting them repeatedly in tight loops. {% endhint %} ## Concepts ### Browser instance Represents a provisioned browser session. | Field Name | Description | Type | | --------------- | ---------------------------------------------- | ------ | | `session_id` | Unique identifier for the browser session. | `text` | | `live_view_url` | URL to watch the browser session in real time. | `text` | ### Browser action result The result returned after each browser action. | Field Name | Description | Type | | ------------- | ------------------------------------------------------------------------------- | ---------------- | | `success` | Whether the action completed successfully. | `boolean` | | `result` | The action's output (for example, snapshot content, extracted data, PASS/FAIL). | `text` | | `action_type` | The type of action that was performed. | `text` | | `snapshot` | A structured view of the page after the action (when available). | `optional[text]` | # Browser Use Overview of the Browser Use integration. {% hint style="info" %} The following documentation is for **Browser Use v3.0.0**. {% endhint %} ## Overview The **Browser Use** book enables you to perform **web automation** using natural language. Use plain English to describe a task, and a remote browser agent will execute it. The browser agent can perform a range of web automation tasks, including navigating pages, filling out forms, and extracting structured data, all with full traceability. Every action is logged with detailed step plans and unique session IDs. Take a look at this quick example: {% embed url="" %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Browser Use** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. The **Browser Use** book can be used with or without credentials. ## Getting Started ## Best Practices ## Actions The following actions are available in the **Browser Use** integration: ### 1. Close a browser Close a browser instance. ### 2. Perform a task on a browser and get the visual log, the detailed plan, the result, the browser run id and the browser files Execute a browser-based web automation task. ### 3. Provision a browser Provision a new K8s browser instance for a web automation task. ### 4. Provision an aws browser Provision a new AWS AgentCore browser instance for a web automation task. ### 5. Run a playwright script on a browser and get the result, the browser run id and the browser files Execute a custom Playwright script on the provisioned browser. ## Concepts ### Browser instance Represents attributes of an instance with browser support. | Field Name | Description | Type | | -------------- | -------------------------------------------------------------- | ---------------- | | `browser_name` | The name of the browser instance (pod name or AWS session ID). | `text` | | `vnc` | The Virtual Network Computing (VNC) URL to access the browser. | `text` | | `browser_type` | The type of browser backend ("k8s" or "aws"). | `optional[text]` | ### Browser task Represents a browser automation task. | Field Name | Description | Type | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | | `instructions` | A natural language description of the task for the browser agent to perform (e.g., "Log into my account on example.com and check for new messages"). | `text` | | `browser_task_id` | Identifier for the browser task. | `text` | | `output` | The desired structure or format of the results. It is recommended to use key-value pairs for clarity (e.g., {"key": "value"}). If specified, the agent will format the result accordingly. | `optional[text]` | | `worker_id` | Identifier for the Kognitos worker executing the task. | `text` | | `line_id` | Identifier for the specific line/step in the Kognitos automation. | `text` | | `browser_task_version` | Version of the browser task. | `text` | | `task_context` | Optional additional context or data to assist in completing the task. Contains the resolved reference facts for the task. | `optional[json]` | | `credential_names` | The names of the authentication credentials needed for the task. | `optional[list of text]` | | `files` | The files to be uploaded to the browser. | `optional[list of text]` | # Confluence Overview of the Confluence integration. {% hint style="info" %} The following documentation is for **Confluence v1.2.0**. {% endhint %} ## Overview Connect to Atlassian Confluence to retrieve and publish content in your team’s collaborative space ## Setup The following integrations need to be connected to your Kognitos workspace: * **Confluence** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Email, Domain and Token Connects to an API using the provided email and Atlassian token. | Label | Description | Type | | ------ | ------------------------------------------ | ----------- | | Email | The email address for authentication | `text` | | Domain | The domain of the Atlassian account | `text` | | Token | The Atlassian API token for authentication | `sensitive` | ## Actions The following actions are available in the **Confluence** integration: ### 1. Create a page in a space Creates a page in Confluence ### 2. Retrieve some pages from confluence Retrieves pages from Confluence ### 3. Retrieve some spaces from confluence Retrieves spaces from Confluence ## Concepts ### Confluence space A Space in Confluence | Field Name | Description | Type | | ---------- | ---------------------------------- | ------ | | `id` | The unique identifier of the space | `text` | | `name` | The name of the space | `text` | ### Confluence page A Page in Confluence | Field Name | Description | Type | | ---------- | --------------------------------- | ------ | | `id` | The unique identifier of the page | `text` | | `title` | The title of the page | `text` | | `content` | The content of the page | `text` | # CSV Overview of the CSV integration. {% hint style="info" %} The following documentation is for **CSV v1.8.0**. {% endhint %} ## Overview Enables converting and reading CSV files. ## Setup The following integrations need to be connected to your Kognitos workspace: * **CSV** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **CSV** integration: ### 1. Convert csv to table Convert a CSV file to a table. ### 2. Get csv column Get the values from a specific column in a CSV file. ### 3. Get csv column types Get the data types for all columns in a CSV file. ### 4. Get csv headers Get the column headers from a CSV file. ### 5. Get csv row count Get the number of rows in a CSV file, excluding the header row. # Databricks Overview of the Databricks integration. {% hint style="info" %} The following documentation is for **Databricks v1.1.0**. {% endhint %} ## Overview Databricks is a unified analytics platform for data engineering, data science, and machine learning. This integration enables automated data pipeline management, notebook execution, and analytics workflows within your Databricks workspace. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Databricks** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Cluster URL and Access Token Connects to Databricks using the provided access token. | Label | Description | Type | | ------------ | ------------------------------------------ | ----------- | | Cluster URL | The Databricks cluster URL | `text` | | Access Token | The access token to be used for connecting | `sensitive` | ## Actions The following actions are available in the **Databricks** integration: ### 1. Append a file to a table Append data from a file to an existing table. ### 2. Append a table to a databricks table Append data from a Kognitos table to an existing Databricks table. ### 3. Create a databricks table from a table Create a table in Databricks from a Kognitos table. ### 4. Create databricks table from a file Create a table from an uploaded file. ### 5. Get a catalog Get a catalog by its name. ### 6. Get file at a path Get file metadata for a file at the given path. ### 7. Get some catalog's schema Get a schema from a catalog by its name. ### 8. Get some warehouses List all warehouses in the workspace. ### 9. Upload a file to databricks Upload a file to a catalog volume. ## Concepts ### Databricks warehouse Warehouse in Databricks. | Field Name | Description | Type | | ---------- | -------------------------------------- | ------ | | `id` | The unique identifier of the warehouse | `text` | | `name` | The name of the warehouse | `text` | ### Databricks file File in Databricks. | Field Name | Description | Type | | ------------- | ---------------------------------------------------- | ------ | | `schema` | The schema containing the file | `json` | | `path` | The path to the file | `text` | | `file_type` | The MIME type of the file | `text` | | `file_format` | The file format extension (e.g., csv, json, parquet) | `text` | ### Databricks schema Schema in Databricks. | Field Name | Description | Type | | ---------- | ---------------------------------- | ------ | | `name` | The name of the schema | `text` | | `catalog` | The catalog containing this schema | `json` | ### Databricks catalog Catalog in Databricks. | Field Name | Description | Type | | ---------- | ----------------------- | ------ | | `name` | The name of the catalog | `text` | # DOCX Overview of the DOCX integration. {% hint style="info" %} The following documentation is for **DOCX v1.8.0**. {% endhint %} ## Overview An integration for working with DOCX template files. ## Setup The following integrations need to be connected to your Kognitos workspace: * **DOCX** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **DOCX** integration: ### 1. Convert a docx file Converts a DOCX file to the specified format. ### 2. Fill a docx template Fills in a DOCX template with provided data. ### 3. Get some template fields Retrieves all placeholder fields from a DOCX template. # EC2 Overview of the EC2 integration. {% hint style="info" %} The following documentation is for **EC2 v1.6.4**. {% endhint %} ## Overview Manages network security for EC2 by controlling access to resources. ## Setup The following integrations need to be connected to your Kognitos workspace: * **EC2** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID Assumes a role using the provided AWS credentials. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID for the initial authentication. | `text` | | AWS Secret Access Key | The AWS Secret Access Key for the initial authentication. | `sensitive` | | AWS Region | The AWS Region for the initial authentication. | `text` | | AWS Role ARN | The ARN of the role to assume. | `text` | | AWS External ID | An optional external ID that might be required by the role's trust policy. | `sensitive` | ### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region Connects to an API using the provided API key. | Label | Description | Type | | --------------------- | ------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID | `text` | | AWS Secret Access Key | The AWS Secret Access Key | `sensitive` | | AWS Region | The AWS Region | `text` | ## Actions The following actions are available in the **EC2** integration: ### 1. Attach a rule to a security group Create an ingress or egress rule in a security group. ### 2. Get security groups from ec2 Get security groups from EC2. ### 3. Get some security group's rules Get security group rules for a security group in EC2. ### 4. Revoke a security group rule Delete a security group rule from a security group. ## Concepts ### Ec2 security group Represents an EC2 security group. | Field Name | Description | Type | | ------------------ | ------------------------------------------------------ | ----------------- | | `id` | The ID of the security group. | `text` | | `name` | The name of the security group. | `text` | | `description` | The description of the security group. | `text` | | `vpc_id` | The ID of the VPC to which the security group belongs. | `text` | | [`tags`](#aws-tag) | A list of tags associated with the security group. | `list of aws tag` | ### Aws tag Represents an AWS tag. | Field Name | Description | Type | | ---------- | --------------------- | ------ | | `key` | The key of the tag. | `text` | | `value` | The value of the tag. | `text` | ### Ec2 ip permission Represents an IP permission for an EC2 security group. | Field Name | Description | Type | | ------------------------------------------------------- | ----------------------------------------------- | ------------------------ | | `ip_protocol` | The IP protocol for the permission. | `text` | | `from_port` | The start port for the permission. | `number` | | `to_port` | The end port for the permission. | `number` | | [`ip_ranges`](#ip_ranges-ec2-ip-permission) | The list of IP ranges for the permission. | `optional[list of json]` | | [`ipv6_ranges`](#ipv6_ranges-ec2-ip-permission) | The list of IPv6 ranges for the permission. | `optional[list of json]` | | [`prefix_list_ids`](#prefix_list_ids-ec2-ip-permission) | The list of prefix list IDs for the permission. | `optional[list of json]` | ### Ec2 security group rule Represents an EC2 security group rule. | Field Name | Description | Type | | ------------------ | ------------------------------------------------------------------ | ----------------- | | `rule_id` | The ID of the security group rule. | `text` | | `group_id` | The ID of the security group. | `text` | | `group_owner_id` | The AWS account ID of the security group owner. | `text` | | `is_egress` | Whether the rule is an egress rule (True) or ingress rule (False). | `boolean` | | `ip_protocol` | The IP protocol for the rule. | `text` | | `from_port` | The start port (or ICMP type) for the rule. | `number` | | `to_port` | The end port (or ICMP code) for the rule. | `number` | | [`tags`](#aws-tag) | A list of tags associated with the security group rule. | `list of aws tag` | | `rule_arn` | The ARN of the security group rule. | `text` | | `cidr_ipv4` | The IPv4 CIDR range for the rule, if applicable. | `optional[text]` | | Name | Type | | | ------------- | ---------------- | | | `description` | `optional[text]` | | | `cidr_ip` | `optional[text]` | | | Name | Type | | | ------------- | ---------------- | | | `description` | `optional[text]` | | | `cidr_ipv6` | `optional[text]` | | | Name | Type | | | ---------------- | ---------------- | | | `description` | `optional[text]` | | | `prefix_list_id` | `optional[text]` | | # EML Overview of the EML integration. {% hint style="info" %} The following documentation is for **EML v1.8.0**. {% endhint %} ## Overview Enables reading EML files. ## Setup The following integrations need to be connected to your Kognitos workspace: * **EML** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **EML** integration: ### 1. Check eml has attachments Check if a EML file has attachments. ### 2. Check eml is forward Check if a EML file is a forwarded email. ### 3. Check eml is reply Check if a EML file is a reply to another email. ### 4. Get eml attachments Get the attachments from a EML file as IO objects. ### 5. Get eml bcc recipients Get the BCC recipients from a EML file. ### 6. Get eml body Get the body from a EML file. ### 7. Get eml cc recipients Get the CC recipients from a EML file. ### 8. Get eml date Get the date from a EML file. ### 9. Get eml message identifier Get the Message-ID from a EML file. ### 10. Get eml parent message identifier Get the In-Reply-To header from a EML file. ### 11. Get eml reply address Get the Reply-To address from a EML file. ### 12. Get eml sender Get the sender from a EML file. ### 13. Get eml subject Get the subject from a EML file. ### 14. Get eml to recipients Get the To recipients from a EML file. # Epicor Overview of the Epicor integration. {% hint style="info" %} The following documentation is for **Epicor v1.2.0**. {% endhint %} ## Overview Discover business entities and automate ERP workflows within Epicor. {% hint style="success" %} The Epicor integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Epicor** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your Epicor connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Host, Environment, Company, Username, Password and API Key Connects to an API using the provided API key. | Label | Description | Type | | ----------- | ------------------------------------- | ------ | | Host | The Epicor server URL | `text` | | Environment | The Epicor environment | `text` | | Company | The Epicor company ID | `text` | | Username | The username for authentication | `text` | | Password | The password for authentication | `text` | | API Key | The API key to be used for connecting | `text` | ## Actions The following actions are available in the **Epicor** integration: ### 1. Get method info from epicor Gets the parameter info for a custom method on an Epicor service. ### 2. Invoke a method on epicor Invokes a custom method on an Epicor Business Object service. ### 3. Retrieve some baqs from epicor Retrieves the list of available Business Activity Queries (BAQs). ### 4. Retrieve some entities from epicor Retrieves the list of available Epicor entities for a given service. {% hint style="info" %} In addition to these built-in actions, the Epicor integration supports **custom actions** that are discovered from your specific system. The actions available depend on which services you enable through the [discovery process](#discovering-actions). {% endhint %} ## Concepts ### Epicor entity Represents an Epicor entity with its metadata.This includes both regular entities and Business Activity Queries (BAQs). | Field Name | Description | Type | | --------------- | -------------------------------------------------- | ------ | | `name` | The name of the entity or BAQ. | `text` | | `kind` | The kind of the entity (e.g., "EntitySet", "BAQ"). | `text` | | `url` | The URL of the entity or BAQ. | `text` | | `discover_call` | The discovery call for the entity or BAQ. | `text` | # Excel Overview of the Excel integration. {% hint style="info" %} The following documentation is for **Excel v1.3.3**. {% endhint %} ## Overview Enables reading, creating, and modifying offline Excel files (xlsx, xlsm, xls, xlsb) without requiring a network connection or Microsoft account. This integration provides file-based spreadsheet operations for agents that need to work with Excel files directly. It supports creating new spreadsheets, reading worksheet data, extracting structured tables, managing worksheets (add, remove, copy, rename), cell-level reads and writes, row and column insertion, bulk cell updates, and formula insertion across row ranges. Read support covers all major Excel formats (.xlsx, .xlsm, .xls, .xlsb). Write and modification operations are supported for .xlsx and .xlsm formats only. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Excel** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **Excel** integration: ### 1. Add a filter to a worksheet Add auto-filter to a worksheet. ### 2. Add a worksheet to an excel Add an empty worksheet to an Excel file. ### 3. Add data validation to a worksheet Add data validation to a range of cells. ### 4. Append data to a range Append data from a table at a specific cell position. ### 5. Append data to a worksheet Append rows from a table to the end of a worksheet. ### 6. Autofill a range in a worksheet Auto-fill a target range based on the pattern in the source range. ### 7. Copy a worksheet in the excel Copy a worksheet within an Excel file. ### 8. Create an excel Create a new Excel file with one or more worksheets. ### 9. Delete columns from a worksheet Delete one or more columns from a worksheet. ### 10. Delete rows from a worksheet Delete one or more rows from a worksheet. ### 11. Export a worksheet to csv Export a worksheet to CSV or TSV format. ### 12. Extract a table from a worksheet Extract a structured table from a worksheet. ### 13. Format cells in a worksheet Format cells in a worksheet with background color, font color, weight, and size. ### 14. Get a cell's value from a worksheet Get the value of a specific cell from a worksheet. ### 15. Get a range from a worksheet Get cell values from a range in a worksheet. ### 16. Get a worksheet's cell's formula Get the formula from a specific cell in a worksheet. ### 17. Get an excel's worksheet Get a single worksheet from an Excel file by name. ### 18. Get an excel's worksheet names Get the list of worksheet names from an Excel file. ### 19. Get an excel's worksheets Get all worksheets from an Excel file at once. ### 20. Insert a formula into an excel Insert formulas into a column across a range of rows. ### 21. Insert a table into a worksheet Insert a table into a worksheet at a specified location. ### 22. Insert a vlookup formula into a worksheet Insert a VLOOKUP formula into a cell. ### 23. Insert columns into a worksheet Insert one or more columns into a worksheet. ### 24. Insert rows into a worksheet Insert one or more rows into a worksheet. ### 25. Merge cells in a worksheet Merge cells in a worksheet. ### 26. Protect a worksheet Protect a worksheet from editing. ### 27. Read content from an excel Read the content of an Excel, CSV, or TSV file as a markdown string. ### 28. Remove a worksheet Remove a worksheet from an Excel file. ### 29. Rename a worksheet in the excel Rename a worksheet in an Excel file. ### 30. Replace values in a worksheet Find and replace text values in a worksheet. ### 31. Set a worksheet's cell to a string Set the value of a cell in a worksheet. ### 32. Sort a worksheet Sort rows in a worksheet by a specified column. ### 33. Split a column in a worksheet Split text in a column into multiple columns by a delimiter. ### 34. Unmerge cells in a worksheet Unmerge previously merged cells in a worksheet. ### 35. Unprotect a worksheet Remove protection from a worksheet. ### 36. Update an excel's cell values Update multiple cell values in a worksheet at once. ## Concepts ### Excel table A structured data table extracted from an Excel worksheet, with named columns and typed rows.This class represents a table that was extracted from a worksheet. It contains the table data and extraction context. | Field Name | Description | Type | | ------------------- | ----------------------------------------------------------- | ---------------- | | `data` | PyArrow table containing the extracted table data | `table` | | `source_worksheet` | Name of the worksheet this table was extracted from | `optional[text]` | | `location` | Cell range where table was found (e.g., "A1:D10") | `optional[text]` | | `extraction_method` | How the table was extracted ("location", "headers", "full") | `optional[text]` | ### Excel worksheet A single sheet within an Excel workbook containing rows and columns of cell data.This class contains the worksheet data and basic identifying information. Metadata (row\_count, column\_count) is computed from data, not stored separately. | Field Name | Description | Type | | ----------------- | ------------------------------------------------------------ | ------------------ | | `name` | Name of the worksheet | `text` | | `data` | PyArrow table containing the worksheet data | `table` | | `excel_file_name` | Name of the parent Excel file (string reference, not object) | `text` | | `_row_count` | Cached row count (computed from data) | `optional[number]` | | `_column_count` | Cached column count (computed from data) | `optional[number]` | # File Overview of the File integration. {% hint style="info" %} The following documentation is for **File v1.8.0**. {% endhint %} ## Overview Enables reading, writing, and manipulating files. ## Setup The following integrations need to be connected to your Kognitos workspace: * **File** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **File** integration: ### 1. Get the file's extension Get the extension of a file. ### 2. Get the file's mime type Get the MIME type of a file. ### 3. Get the file's name Get the name of a file. ### 4. Get the file's size Get the size of a file in a human-readable format. ### 5. Read the file Read the contents of a file as a string. ### 6. Read the file as a base64 string Read the contents of a file as a base64-encoded string. ### 7. Rename a file Rename a file by changing its filename and/or extension. ### 8. Write a file Create a file with the specified content. # FileMaker Overview of the FileMaker integration. {% hint style="info" %} The following documentation is for **FileMaker v1.1.4**. {% endhint %} ## Overview FileMaker by Claris enables you to build custom apps and manage data. This integration allows you to automate data operations, record management, and custom application workflows. {% hint style="success" %} The FileMaker integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **FileMaker** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} #### Open the connection menu Navigate to **Integrations**, find your FileMaker connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} #### Browse and enable services Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} #### Save and wait Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using URL, Username and Password Connects to the FileMaker API using basic authentication. | Label | Description | Type | | -------- | ------------------------------------------------ | ----------- | | URL | The base URL of the FileMaker OData API endpoint | `text` | | Username | The username for authentication | `text` | | Password | The password for authentication | `sensitive` | # Fizzy Overview of the Fizzy integration. {% hint style="info" %} The following documentation is for **Fizzy v1.0.0**. {% endhint %} ## Overview Enables interacting with Fizzy for kanban-based issue and idea tracking. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Fizzy** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Personal Access Token Connect to Fizzy using a personal access token. | Label | Description | Type | | ------------ | --------------------------------------------------------------------- | ----------- | | Access Token | Your personal access token from Fizzy profile settings. | `sensitive` | | Account Slug | The numeric account slug from your Fizzy URL. | `text` | | Base URL | The Fizzy instance URL. Use the default for fizzy.do hosted accounts. | `text` | ## Actions {% hint style="info" %} The available actions for **Fizzy** are listed in the product UI on the integration page once you create a connection. {% endhint %} # Gemini Overview of the Gemini integration. {% hint style="info" %} The following documentation is for **Gemini v1.1.4**. {% endhint %} ## Overview A Gemini integration for interacting with Google's Gemini models. This integration provides LLM functionality by connecting to the Google AI or Vertex AI API. It supports both API key authentication (Google AI) and service account authentication (Vertex AI). ## Setup The following integrations need to be connected to your Kognitos workspace: * **Gemini** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using API Key Connect using an API key. | Label | Description | Type | | ------- | ------------------------------- | ----------- | | API Key | The API key for authentication. | `sensitive` | ### Connect using Service Account JSON and Location Connect to Gemini using a Google Cloud service account (Vertex AI). | Label | Description | Type | | -------------------- | ------------------------------------------------ | ----------- | | Service Account JSON | The complete service account JSON. | `sensitive` | | Location | The Google Cloud location (e.g., 'us-central1'). | `text` | ## Actions The following actions are available in the **Gemini** integration: ### 1. Prompt gemini Send a prompt to the Gemini LLM and get a response. # GitHub Overview of the GitHub integration. {% hint style="info" %} The following documentation is for **GitHub v2.0.1**. {% endhint %} ## Overview GitHub is the world's leading platform for version control and collaborative software development. This integration enables automated repository management, issue tracking, pull request operations, and code deployment workflows. Streamline your development processes and enhance team collaboration on code projects. ## Setup The following integrations need to be connected to your Kognitos workspace: * **GitHub** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using API Key Connect to the GitHub API using an API key. | Label | Description | Type | | ------- | ------------------------------------- | ----------- | | API Key | The API key to be used for connecting | `sensitive` | ## Actions The following actions are available in the **GitHub** integration: ### 1. Create a pull request in a repository source Create a pull request for a specified GitHub repository. ### 2. Create an issue in a repository source Create an issue for a specified GitHub repository. ### 3. Get the commits from a repository source Get the commits from a GitHub repository. ### 4. Get the issues from a repository source Get the issues from a GitHub repository. ### 5. Get the pull request from a repository source Get a pull request from a GitHub repository. ### 6. Get the pull requests from a repository source Get the pull requests from a GitHub repository. ### 7. Get the repositories from a source organization Get the repositories from a GitHub organization. ### 8. Get the team from a source organization Get a team from a GitHub organization. ### 9. Get the teams from a source organization Get the teams from a GitHub organization. ### 10. Get the user from a name Get a user from GitHub. ### 11. Request reviewers for a pull request Request reviewers for a pull request in a specified GitHub repository. ### 12. Update a pull request in a repository source Update a pull request for a specified GitHub repository. ### 13. Update an issue in a repository source Update an issue for a specified GitHub repository. ## Concepts ### Github issue GitHub Issue Wrapper class. | Field Name | Description | Type | | ------------------------- | -------------------------------------------------------------------------------- | -------------------------------- | | `number` | The number of the issue. Optional since is None in case of creating an issue. | `optional[number]` | | `title` | The title of the issue. Optional since can be None in case of editing an issue. | `optional[text]` | | `body` | The body of the issue. Optional since can be None in case of editing an issue. | `optional[text]` | | `state` | The state of the issue. Optional since is None in case of creating an issue. | `optional[text]` | | [`labels`](#github-label) | The labels of the issue. Optional since can be None in case of editing an issue. | `optional[list of github label]` | | [`user`](#github-user) | The user of the issue. Optional since is None in case of creating an issue. | `optional[github user]` | ### Github label GitHub Label Wrapper class. | Field Name | Description | Type | | ------------- | ----------------------------- | ---------------- | | `color` | The color of the label. | `text` | | `description` | The description of the label. | `optional[text]` | | `name` | The name of the label. | `text` | | `url` | The URL of the label. | `text` | ### Github user GitHub User Wrapper class. | Field Name | Description | Type | | ---------- | ---------------------- | ------------------ | | `login` | The login of the user. | `optional[text]` | | `id` | The ID of the user. | `optional[number]` | | `type` | The type of the user. | `optional[text]` | ### Github pull request GitHub Pull Request Wrapper class. | Field Name | Description | Type | | ---------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `number` | The number of the pull request. Optional since is None in case of creating a pull request. | `optional[number]` | | `head` | The head of the pull request. Optional since can be None in case of editing a pull request. | `optional[github pull request part?` or `text]` | | `title` | The title of the pull request. Optional since can be None in case of editing a pull request. | `optional[text]` | | `base` | The base of the pull request. Optional since can be None in case of editing a pull request. | `optional[github pull request part?` or `text]` | | `body` | The body of the pull request. Optional since can be None in case of editing a pull request. | `optional[text]` | | `state` | The state of the pull request. Optional since is None in case of creating a pull request. | `optional[text]` | ### Github commit GitHub Commit Wrapper class. | Field Name | Description | Type | | ------------------------------- | ---------------------- | ------------------------------- | | [`commit`](#github-git-commit) | The commit. | `optional[github git commit]` | | `sha` | The SHA of the commit. | `optional[text]` | | [`stats`](#github-commit-stats) | The commit stats. | `optional[github commit stats]` | | `url` | The URL of the commit. | `optional[text]` | ### Github git commit GitHub Git Commit Wrapper class. | Field Name | Description | Type | | --------------------------------- | ---------------------------- | ----------------------------- | | [`author`](#github-git-author) | The author of the commit. | `optional[github git author]` | | [`committer`](#github-git-author) | The committer of the commit. | `optional[github git author]` | | `message` | The message of the commit. | `optional[text]` | | `sha` | The SHA of the commit. | `optional[text]` | ### Github commit stats GitHub Commit Stats Wrapper class. | Field Name | Description | Type | | ----------- | ---------------------------- | -------- | | `total` | The total number of commits. | `number` | | `deletions` | The number of deletions. | `number` | | `additions` | The number of additions. | `number` | ### Github repository GitHub Repository Wrapper class. | Field Name | Description | Type | | ----------------- | ---------------------------------- | ------ | | `branches_url` | The branches URL. | `text` | | `commits_url` | The commits URL. | `text` | | `description` | The description of the repository. | `text` | | `git_commits_url` | The git commits URL. | `text` | | `git_tags_url` | The git tags URL. | `text` | | `git_url` | The git URL. | `text` | | `name` | The name of the repository. | `text` | ### Github team GitHub Team Wrapper class. | Field Name | Description | Type | | ------------------------- | --------------------------------- | ------------------------------- | | `id` | The ID of the team. | `number` | | `url` | The URL of the team. | `text` | | `name` | The name of the team. | `text` | | `slug` | The slug of the team. | `text` | | `description` | The description of the team. | `text` | | `privacy` | The privacy of the team. | `text` | | `permission` | The permission of the team. | `text` | | [`members`](#github-user) | The members of the team. | `optional[list of github user]` | | `members_url` | The members URL of the team. | `optional[text]` | | `repositories_url` | The repositories URL of the team. | `text` | # GitLab Overview of the GitLab integration. {% hint style="info" %} The following documentation is for **GitLab v1.0.0**. {% endhint %} ## Overview GitLab is a DevSecOps platform that provides Git repository management, CI/CD pipelines, issue tracking, and code review. This integration allows you to manage your GitLab resources programmatically. ## Setup The following integrations need to be connected to your Kognitos workspace: * **GitLab** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Personal Access Token Connect to GitLab using a Personal Access Token. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | Personal Access Token | Your Personal Access Token from GitLab. Found in User Settings > Access Tokens. | `sensitive` | | GitLab Instance URL | The GitLab instance URL. Defaults to "" for GitLab.com. For self-managed instances, use your instance URL (e.g. ""). | `text` | ## Actions {% hint style="info" %} The available actions for **GitLab** are listed in the product UI on the integration page once you create a connection. {% endhint %} # Gmail Overview of the Gmail integration. {% hint style="info" %} The following documentation is for **Gmail v2.2.0**. {% endhint %} ## Overview Gmail is Google's comprehensive email service providing powerful messaging, organization, and collaboration features. This integration enables automated email sending, inbox management, message filtering, and email workflow automation. Streamline communication processes and enhance productivity through intelligent email automation. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Gmail** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use Google OAuth to connect this integration in Kognitos. {% hint style="info" %} If your organization uses its own Google OAuth app, follow [Google Authentication](/guides/platform/integrations/google-authentication). You can reuse the same Client ID and Client Secret for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. {% endhint %} ### Continue with Google To connect to the **Gmail** integration, click on Continue with Google. This redirects you to Google's secure authentication page, where you can sign in with your Google account and authorize the application. Once connected, Kognitos can access your Gmail account without storing your Google credentials directly. ## Actions The following actions are available in the **Gmail** integration: ### 1. Add a label to an email Add a label to one or more emails. ### 2. Download an email's attachments Get an email attachment as an IO object. ### 3. Forward an email Forward an email to new recipients. ### 4. Get some label's emails Get emails from a specified label in Gmail. ### 5. List labels Get all labels from the user's Gmail account. ### 6. Remove a label from an email Remove a label from one or more emails. ### 7. Reply an email Reply to an email. ### 8. Send an email Send an email using Gmail API. ## Concepts ### Gmail email A Gmail Email represents an email message in Gmail. | Field Name | Description | Type | | -------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- | | `id` | The unique identifier for the email. | `text` | | `thread_id` | The unique identifier for the thread containing the email. | `text` | | [`labels`](#list-of-text) | The list of labels applied to the email. | `list of text` | | `state` | The state of the email (draft, unread, or read). | `text` | | `sender` | The sender of the email. | `text` | | [`recipients`](#list-of-text) | The recipients of the email. | `list of text` | | `message_id` | The unique identifier for the message. | `optional[text]` | | `cc_recipients` | The cc recipients of the email. | `optional[list of text]` | | `bcc_recipients` | The bcc recipients of the email. | `optional[list of text]` | | [`attachments`](#gmail-attachment-reference) | The attachments of the email. | `optional[list of gmail attachment reference]` | | `subject` | The subject of the email. | `optional[text]` | | `plain_body` | The plain text body of the email. | `optional[text]` | | `html_body` | The html body of the email. | `optional[text]` | | `sent_date_time` | The date and time the email was sent. | `optional[datetime]` | | `received_date_time` | The date and time the email was received. | `optional[datetime]` | ### Gmail attachment reference A Gmail Attachment Reference represents a reference to a file attached to an email in Gmail. | Field Name | Description | Type | | ----------- | ----------------------------------------- | -------- | | `id` | The unique identifier for the attachment. | `text` | | `email_id` | The unique identifier for the email. | `text` | | `file_name` | The name of the attachment. | `text` | | `file_size` | The size of the file in bytes. | `number` | ### Gmail attachment A Gmail Attachment represents a file with name. | Field Name | Description | Type | | ----------- | ------------------------------ | ------ | | `file_name` | The name of the attachment. | `text` | | `content` | The content of the attachment. | `file` | # Google Authentication Set up shared Google OAuth authentication for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. Use this guide when you connect a Google integration in Kognitos with Continue with Google. You can create one Google OAuth app in Google Cloud and reuse the same **Client ID** and **Client Secret** across these integrations: * [Gmail](/guides/platform/integrations/gmail) * [Google Calendar](/guides/platform/integrations/calendar) * [Google Chat](/guides/platform/integrations/chat) * [Google Docs](/guides/platform/integrations/docs) * [Google Drive](/guides/platform/integrations/drive) * [Google Sheets](/guides/platform/integrations/sheets) {% hint style="info" %} Google Docs, Google Drive, and Google Sheets also support service account authentication. This page covers the shared OAuth setup that works across all six Google integrations. For service account setup, see [Google Service Account Authentication](/guides/platform/integrations/google-service-account-authentication). {% endhint %} ## Before You Start Make sure you have: * Access to a Google Cloud project, or permission to create one * Permission to configure the Google Auth Platform and create OAuth clients * Access to the Kognitos workspace where you want to add the connection If your organization wants to avoid Google's unverified app warning, create the OAuth app as an **Internal** app in your Google Workspace organization. ## Set Up the OAuth App in Google Cloud {% stepper %} {% step %} **Create or select a Google Cloud project** In [Google Cloud Console](https://console.cloud.google.com/), create a new project or open an existing one that will own the OAuth app.
{% endstep %} {% step %} **Configure the consent screen** In **Google Auth Platform**, set up the consent screen for the project: 1. Enter an app name. 2. Select a user support email. 3. Choose **Internal** as the audience if the app should only be used by people in your Google Workspace organization. 4. Add a contact email. 5. Accept Google's user data policy and save the configuration.
{% endstep %} {% step %} **Create the OAuth client** Create a new client with these settings: * **Application type:** Web application * **Authorized redirect URI:** `https://app.us-1.kognitos.com/oauth/connections/callback`
Copy the **Client ID** and **Client Secret** after you create the client. Store the secret somewhere secure in case Google only shows it once. {% hint style="warning" %} Use the production redirect URI exactly as shown. Do not use the dev URL or a legacy callback URL. {% endhint %}
{% endstep %} {% step %} **Enable the APIs you need** In APIs & Services → Library, enable the APIs for the Google integrations you plan to use: | Integration | API to enable | | --------------------------------------------------------- | -------------------------------------------- | | [Gmail](/guides/platform/integrations/gmail) | **Gmail API** | | [Google Calendar](/guides/platform/integrations/calendar) | **Google Calendar API** | | [Google Chat](/guides/platform/integrations/chat) | **Google Chat API** | | [Google Docs](/guides/platform/integrations/docs) | **Google Docs API** and **Google Drive API** | | [Google Drive](/guides/platform/integrations/drive) | **Google Drive API** | | [Google Sheets](/guides/platform/integrations/sheets) | **Google Sheets API** |
If you plan to use several Google integrations, enable all of their APIs in the same project. {% hint style="info" %} If you use [Google Chat](/guides/platform/integrations/chat), open the Google Chat API configuration after you enable the API and complete the app details before you connect it in Kognitos: * **App name:** for example, `Kognitos` * **Avatar URL:** `https://www.kognitos.com/img/favicon.svg` * **Description:** for example, `Google Chat integration with Kognitos` * Enable **Build this Chat app as a Workspace add-on** * Disable **Interactive features** {% endhint %}
{% endstep %} {% endstepper %} ## Use the Credentials in Kognitos After you create the OAuth client in Google Cloud, connect each Google integration in Kognitos with the same credentials. {% stepper %} {% step %} **Open the integration** In Kognitos, go to Integrations → Explore Integrations, then open the Google integration you want to connect. {% endstep %} {% step %} **Start a new connection** Click Connect, add a connection name, and choose the OAuth option if Kognitos asks you to select an authentication method.
{% endstep %} {% step %} **Enter your OAuth client details** Paste the **Client ID** and **Client Secret** from Google Cloud.
{% endstep %} {% step %} **Authorize with Google** Click Continue with Google, sign in to Google, grant access, and return to Kognitos. {% endstep %} {% endstepper %} Repeat this for each Google integration you want to connect. You can reuse the same OAuth app across all six integrations. ## Troubleshooting | Issue | What to check | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Redirect URI mismatch | Confirm the redirect URI is exactly `https://app.us-1.kognitos.com/oauth/connections/callback` | | Unverified app warning | Make sure the OAuth app audience is set to **Internal**, and the user belongs to the same Google Workspace organization | | Access blocked | Verify that the API for the integration is enabled in the Google Cloud project | | Missing client secret | Create a new client secret in Google Cloud, then update the connection in Kognitos | ## Related Integration Pages * [Gmail](/guides/platform/integrations/gmail) * [Google Calendar](/guides/platform/integrations/calendar) * [Google Chat](/guides/platform/integrations/chat) * [Google Docs](/guides/platform/integrations/docs) * [Google Drive](/guides/platform/integrations/drive) * [Google Sheets](/guides/platform/integrations/sheets) # Google Calendar Overview of the Google Calendar integration. {% hint style="info" %} The following documentation is for **Google Calendar v2.2.0**. {% endhint %} ## Overview Google Calendar provides intelligent scheduling and calendar management with smart automation features. This integration enables automated event creation, scheduling workflows, and calendar synchronization processes. Improve time management and automate scheduling coordination across teams and organizations. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Google Calendar** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use Google OAuth to connect this integration in Kognitos. {% hint style="info" %} If your organization uses its own Google OAuth app, follow [Google Authentication](/guides/platform/integrations/google-authentication). You can reuse the same Client ID and Client Secret for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. {% endhint %} ### Continue with Google To connect to the **Google Calendar** integration, click on Continue with Google. This redirects you to Google's secure authentication page, where you can sign in with your Google account and authorize the application. Once connected, Kognitos can access your Google Calendar without storing your Google credentials directly. ## Actions The following actions are available in the **Google Calendar** integration: ### 1. Create an event Create a new Google Calendar event. ### 2. Get some events Get events from Google Calendar, optionally filtered by time range. ## Concepts ### Google calendar event A Google Calendar event representation. | Field Name | Description | Type | | --------------------- | ----------------------------------------------------------------------- | ------------------------ | | `summary` | The title/summary of the event | `text` | | `start` | The start time of the event | `datetime` | | `end` | The end time of the event | `datetime` | | `id` | The unique identifier for the event (set by Google Calendar) | `optional[text]` | | `description` | Optional description of the event | `optional[text]` | | `location` | Optional location of the event | `optional[text]` | | `attendees` | Optional list of all invited email addresses | `optional[list of text]` | | `confirmed_attendees` | Optional list of confirmed attendee email addresses | `optional[list of text]` | | `potential_attendees` | Optional list of potential attendee email addresses (not yet confirmed) | `optional[list of text]` | | `creator` | Optional email of the event creator | `optional[text]` | | `created` | Optional creation timestamp | `optional[datetime]` | | `updated` | Optional last update timestamp | `optional[datetime]` | | `status` | Optional status of the event (confirmed, tentative, cancelled) | `optional[text]` | | `html_link` | Optional URL to the event in Google Calendar | `optional[text]` | # Google Chat Overview of the Google Chat integration. {% hint style="info" %} The following documentation is for **Google Chat v2.2.0**. {% endhint %} ## Overview Google Chat provides messaging and collaboration inside Google Workspace. This integration lets you list spaces, read and send messages, reply in threads, manage reactions, and check read state information. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Google Chat** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use Google OAuth to connect this integration in Kognitos. {% hint style="info" %} If your organization uses its own Google OAuth app, follow [Google Authentication](/guides/platform/integrations/google-authentication). You can reuse the same Client ID and Client Secret for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. {% endhint %} ### Continue with Google To connect to the **Google Chat** integration, choose **OAuth Authorization Code**, enter your Google OAuth client details if prompted, and continue with Google sign-in to authorize the connection. ## Actions The following actions are available in the **Google Chat** integration: ### 1. Add a reaction to a chat message Add a reaction to a Google Chat message. ### 2. Create a direct message space Create a direct message space in Google Chat. ### 3. Find a direct message space Find an existing direct message space in Google Chat. ### 4. Get a chat message Retrieve a specific Google Chat message. ### 5. Get a chat space Retrieve a specific Google Chat space. ### 6. Get a chat space's read state Retrieve read state information for a Google Chat space. ### 7. Get chat members from a space Retrieve members from a Google Chat space. ### 8. Get chat messages from a space Retrieve messages from a Google Chat space. ### 9. Get reactions from a chat message Retrieve reactions for a Google Chat message. ### 10. Get chat spaces Retrieve Google Chat spaces. ### 11. Get thread messages from a chat message Retrieve replies in a Google Chat thread. ### 12. Send a thread reply Send a reply in a Google Chat thread. ### 13. Send a chat message Send a message in Google Chat. ### 14. Update a chat message Update an existing Google Chat message. # Google Docs Overview of the Google Docs integration. {% hint style="info" %} The following documentation is for **Google Docs v2.2.0**. {% endhint %} ## Overview Google Docs provides collaborative document creation and editing with real-time synchronization across teams. This integration enables automated document generation, content management, and collaborative writing workflows. Enhance documentation processes and improve team collaboration on shared documents. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Google Docs** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. {% hint style="info" %} If you want to connect Google Docs with OAuth, follow [Google Authentication](/guides/platform/integrations/google-authentication). You can reuse the same Client ID and Client Secret for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. {% endhint %} {% hint style="info" %} If you want to connect Google Docs with a service account, follow [Google Service Account Authentication](/guides/platform/integrations/google-service-account-authentication). You can reuse the same service account for Google Docs, Google Drive, and Google Sheets. {% endhint %} ### Connect using Client Email, Token URI and Private Key Gets the credentials from the service account keys. | Label | Description | Type | | ------------ | ------------------------------------------------------------------------------- | ----------- | | Client Email | The client email of the service account registered in the Google Cloud Console. | `text` | | Token URI | The token URI of the Google Cloud Console. | `text` | | Private Key | The private key of the service account registered in the Google Cloud Console. | `sensitive` | ### Continue with Google To connect to the **Google Docs** integration, click on Continue with Google. This redirects you to Google's secure authentication page, where you can sign in with your Google account and authorize the application. Once connected, Kognitos can access your Google Docs without storing your Google credentials directly. ## Actions The following actions are available in the **Google Docs** integration: ### 1. Add a paragraph to a document Adds a new paragraph to the document. ### 2. Create a google document in a folder Creates a new Google Docs document. ## Concepts ### Google drive file reference Contains all information required to identify a file in Google Drive. | Field Name | Description | Type | | -------------------------- | ----------------------------- | -------------- | | `id` | The id of the file | `text` | | `file_name` | The name of the file | `text` | | [`parents`](#list-of-text) | The ids of the parent folders | `list of text` | ### Google drive folder reference Contains all information required to identify a folder in Google Drive. | Field Name | Description | Type | | -------------------------- | ----------------------------- | -------------- | | `id` | The id of the folder | `text` | | `folder_name` | The name of the folder | `text` | | [`parents`](#list-of-text) | The ids of the parent folders | `list of text` | # Google Drive Overview of the Google Drive integration. {% hint style="info" %} The following documentation is for **Google Drive v2.2.0**. {% endhint %} ## Overview Google Drive offers cloud storage and file synchronization with seamless integration across Google Workspace. This integration enables automated file management, sharing workflows, and document organization processes. Streamline file collaboration and maintain synchronized access to important documents. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Google Drive** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. {% hint style="info" %} If you want to connect Google Drive with OAuth, follow [Google Authentication](/guides/platform/integrations/google-authentication). You can reuse the same Client ID and Client Secret for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. {% endhint %} {% hint style="info" %} If you want to connect Google Drive with a service account, follow [Google Service Account Authentication](/guides/platform/integrations/google-service-account-authentication). You can reuse the same service account for Google Docs, Google Drive, and Google Sheets. {% endhint %} ### Connect using Client Email, Token URI and Private Key Gets the credentials from the service account keys. | Label | Description | Type | | ------------ | ------------------------------------------------------------------------------- | ----------- | | Client Email | The client email of the service account registered in the Google Cloud Console. | `text` | | Token URI | The token URI of the Google Cloud Console. | `text` | | Private Key | The private key of the service account registered in the Google Cloud Console. | `sensitive` | ### Continue with Google To connect to the **Google Drive** integration, click on Continue with Google. This redirects you to Google's secure authentication page, where you can sign in with your Google account and authorize the application. Once connected, Kognitos can access your Google Drive without storing your Google credentials directly. ## Actions The following actions are available in the **Google Drive** integration: ### 1. Copy an item to a folder Copy an item to a folder ### 2. Create a folder in another folder Create a (folder) in another folder ### 3. Delete an item Delete an item (file or folder) ### 4. Download a file Download a file ### 5. Get a folder at a path Gets a reference to a folder. ### 6. Get a root folder Gets a reference to the root folder. ### 7. Get some folder's items Lists items from a folder reference ### 8. Move an item to a folder Move an item to a folder ### 9. Rename an item to a name Rename an item (file or folder) to a given name ### 10. Upload a file to a folder Upload a file to a folder ## Concepts ### Google drive file reference Contains all information required to identify a file in Google Drive. | Field Name | Description | Type | | -------------------------- | ----------------------------- | -------------- | | `id` | The id of the file | `text` | | `file_name` | The name of the file | `text` | | [`parents`](#list-of-text) | The ids of the parent folders | `list of text` | ### Google drive folder reference Contains all information required to identify a folder in Google Drive. | Field Name | Description | Type | | -------------------------- | ----------------------------- | -------------- | | `id` | The id of the folder | `text` | | `folder_name` | The name of the folder | `text` | | [`parents`](#list-of-text) | The ids of the parent folders | `list of text` | # Google Service Account Authentication Set up shared Google service account authentication for Google Docs, Google Drive, and Google Sheets. Use this guide when you connect a Google integration in Kognitos with Client Email, Token URI, and Private Key instead of Continue with Google. You can create one Google service account in Google Cloud and reuse it across these integrations: * [Google Docs](/guides/platform/integrations/docs) * [Google Drive](/guides/platform/integrations/drive) * [Google Sheets](/guides/platform/integrations/sheets) {% hint style="info" %} Service account authentication is available for Google Docs, Google Drive, and Google Sheets. Gmail, Google Calendar, and Google Chat use OAuth instead. For OAuth setup, see [Google Authentication](/guides/platform/integrations/google-authentication). {% endhint %} ## Before You Start Make sure you have: * Access to a Google Cloud project, or permission to create one * Permission to create service accounts and download service account keys * Access to the Google files, folders, and spreadsheets you want Kognitos to use * Access to the Kognitos workspace where you want to add the connection {% hint style="warning" %} A service account does not automatically inherit access to your Google Workspace content. You must explicitly share the Google Docs documents, Drive folders, or Sheets files with the service account email. {% endhint %} ## Set Up the Service Account in Google Cloud {% stepper %} {% step %} **Create or select a Google Cloud project** In [Google Cloud Console](https://console.cloud.google.com/), create a new project or open an existing one that will own the service account. {% endstep %} {% step %} **Enable the APIs you need** In APIs & Services → Library, enable the APIs for the integrations you plan to use: | Integration | API to enable | | ----------------------------------------------------- | -------------------------------------------- | | [Google Docs](/guides/platform/integrations/docs) | **Google Docs API** and **Google Drive API** | | [Google Drive](/guides/platform/integrations/drive) | **Google Drive API** | | [Google Sheets](/guides/platform/integrations/sheets) | **Google Sheets API** | If you plan to use several Google integrations, enable all of their APIs in the same project. {% endstep %} {% step %} **Create the service account** In Google Cloud, go to IAM & Admin → Service Accounts, then click Create service account. Enter a clear service account name, such as `kognitos-google-integrations`, review the generated service account ID, then click Done or finish the remaining prompts. {% endstep %} {% step %} **Create and download a JSON key** From IAM & Admin → Service Accounts, locate the service account you just created. Then use one of these console paths, depending on the Google Cloud UI you see: * Open the Actions menu for the service account, click Manage keys, then click Add key → Create new key * Or click the service account email address, open the Keys tab, then click Add key → Create new key Select JSON as the key type, then click Create. Google downloads the JSON key file to your machine. {% hint style="info" %} Google's IAM documentation still describes the Keys tab flow. In some current console layouts, the same flow appears under the service account's Actions menu as Manage keys. {% endhint %} {% hint style="warning" %} Treat the JSON key like a password. Anyone with that file can use the service account until you revoke the key. After Google downloads the key file, you cannot download the same private key again. {% endhint %} {% endstep %} {% endstepper %} ## Get the Values for Kognitos Open the downloaded JSON key file and copy these values into Kognitos: | Kognitos field | JSON field | | ----------------------- | -------------- | | Client Email | `client_email` | | Token URI | `token_uri` | | Private Key | `private_key` | {% hint style="info" %} Paste the full private key value exactly as it appears in the JSON, including the `BEGIN PRIVATE KEY` and `END PRIVATE KEY` lines. {% endhint %} ## Share Google Content with the Service Account Before you test the connection, share the Google content Kognitos needs to access with the service account email from `client_email`. For example: * Share a Google Drive folder with the service account email if your automation will create or read files there * Share a Google Docs document or its parent folder with the service account email if your automation will edit documents * Share a Google Sheets file or its parent folder with the service account email if your automation will read or update spreadsheets Use the same sharing flow you use for any Google account: 1. Open the document, folder, or spreadsheet in Google Workspace. 2. Click Share. 3. Add the service account email. 4. Grant the level of access your automation needs. ## Use the Credentials in Kognitos After you create the service account and download its JSON key, connect each supported Google integration in Kognitos with the same credentials. {% stepper %} {% step %} **Open the integration** In Kognitos, go to Integrations → Explore Integrations, then open [Google Docs](/guides/platform/integrations/docs), [Google Drive](/guides/platform/integrations/drive), or [Google Sheets](/guides/platform/integrations/sheets). {% endstep %} {% step %} **Start a new connection** Click Connect, add a connection name, and choose the service account authentication option. {% endstep %} {% step %} **Enter the service account values** Paste the Client Email, Token URI, and Private Key values from the JSON key file. {% endstep %} {% step %} **Save and test the connection** Click Connect, then run a simple action to confirm the service account can access the files or folders you shared with it. {% endstep %} {% endstepper %} Repeat this for each supported Google integration you want to connect. You can reuse the same service account across all three integrations. ## Troubleshooting | Issue | What to check | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication succeeds, but files are missing | Make sure the document, folder, or spreadsheet is shared with the service account email | | Permission denied | Confirm the service account has the right level of access in Google Workspace | | Invalid private key | Paste the full `private_key` value exactly as it appears in the JSON key | | Access blocked by API settings | Verify that the required API is enabled in the Google Cloud project | | Google Cloud does not let you create a key | Your organization might enforce the `iam.disableServiceAccountKeyCreation` policy. Ask your Google Cloud admin whether service account key creation is blocked for the project. | | Docs integration cannot create files in a folder | Make sure the service account also has access to Google Drive, not just Google Docs | ## Related Integration Pages * [Google Authentication](/guides/platform/integrations/google-authentication) * [Google Docs](/guides/platform/integrations/docs) * [Google Drive](/guides/platform/integrations/drive) * [Google Sheets](/guides/platform/integrations/sheets) # Google Sheets Overview of the Google Sheets integration. {% hint style="info" %} The following documentation is for **Google Sheets v2.2.0**. {% endhint %} ## Overview Google Sheets is a powerful cloud-based spreadsheet application with real-time collaboration capabilities. This integration enables automated data entry, spreadsheet management, and collaborative workflow automation. Streamline data analysis and enhance team productivity through automated spreadsheet operations. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Google Sheets** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. {% hint style="info" %} If you want to connect Google Sheets with OAuth, follow [Google Authentication](/guides/platform/integrations/google-authentication). You can reuse the same Client ID and Client Secret for Gmail, Google Calendar, Google Chat, Google Docs, Google Drive, and Google Sheets. {% endhint %} {% hint style="info" %} If you want to connect Google Sheets with a service account, follow [Google Service Account Authentication](/guides/platform/integrations/google-service-account-authentication). You can reuse the same service account for Google Docs, Google Drive, and Google Sheets. {% endhint %} ### Connect using Client Email, Token URI and Private Key Gets the credentials from the service account keys. | Label | Description | Type | | ------------ | ------------------------------------------------------------------------------- | ----------- | | Client Email | The client email of the service account registered in the Google Cloud Console. | `text` | | Token URI | The token URI of the Google Cloud Console. | `text` | | Private Key | The private key of the service account registered in the Google Cloud Console. | `sensitive` | ### Continue with Google To connect to the **Google Sheets** integration, click on Continue with Google. This redirects you to Google's secure authentication page, where you can sign in with your Google account and authorize the application. Once connected, Kognitos can access your Google Sheets without storing your Google credentials directly. ## Actions The following actions are available in the **Google Sheets** integration: ### 1. Add some content to a table Append content to a Google Sheets table. ### 2. Create a table in a sheet Create a table in a spreadsheet's sheet. ### 3. Create a google spreadsheet in a folder Create a new Google Sheets spreadsheet. ### 4. Get the file's sheets Get the sheets from a Google Sheets file. ### 5. Get the sheet's tables Get the tables from a Google Sheets sheet. ### 6. Insert a new column in the table Create a new column in a Google Sheets table. ### 7. Insert a new row in the table Create a new row in a Google Sheets table. ### 8. Read the content from a table Get the contents of a Google Sheets table. ### 9. Retrieve the columns from the table Get the columns from a Google Sheets table. ### 10. Retrieve the rows from the table Get the rows from a Google Sheets table. ### 11. Write the content in a table Update the contents of a Google Sheets table. ## Concepts ### Google sheet table reference Reference to a table inside a Google Sheets spreadsheet's sheet. | Field Name | Description | Type | | ----------------- | -------------------------- | ------ | | `id` | Id of the table | `text` | | `name` | Name of the table | `text` | | `sheet_reference` | Sheet the table belongs to | `json` | ### Google sheet reference Reference to a sheet inside a Google Sheets spreadsheet file. | Field Name | Description | Type | | ---------- | ------------------------------------- | -------- | | `id` | Id of the sheet | `number` | | `name` | Name of the sheet | `text` | | `file` | spreadsheet file the sheet belongs to | `json` | ### Google drive folder reference Contains all information required to identify a folder in Google Drive. | Field Name | Description | Type | | -------------------------- | ----------------------------- | -------------- | | `id` | The id of the folder | `text` | | `folder_name` | The name of the folder | `text` | | [`parents`](#list-of-text) | The ids of the parent folders | `list of text` | ### Google drive file reference Contains all information required to identify a file in Google Drive. | Field Name | Description | Type | | -------------------------- | ----------------------------- | -------------- | | `id` | The id of the file | `text` | | `file_name` | The name of the file | `text` | | [`parents`](#list-of-text) | The ids of the parent folders | `list of text` | ### Google sheet column reference Reference to a column inside a Google Sheets spreadsheet's sheet. | Field Name | Description | Type | | ---------- | --------------------------- | -------- | | `index` | Index of the column | `number` | | `name` | Name of the column | `text` | | `table` | Table the column belongs to | `json` | ### Google sheet row reference Reference to a row inside a Google Sheets spreadsheet's sheet. | Field Name | Description | Type | | ------------------------ | ------------------------ | --------------------- | | `index` | Index of the row | `number` | | [`values`](#list-of-any) | Values in that row | `list of list of any` | | `table` | Table the row belongs to | `json` | # Google Tasks Overview of the Google Tasks integration. {% hint style="info" %} The following documentation is for **Google Tasks v2.5.0**. {% endhint %} ## Overview Google Tasks provides lightweight task and task-list management integrated with Google Workspace. This integration enables automated task creation, completion, retrieval, and list management workflows. Coordinate to-dos and personal task lists alongside your other automated processes. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Google Tasks** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Continue with Google To connect to the **Google Tasks** book, click on Continue with Google. This will redirect you to Google's secure authentication page where you can sign in with your Google account and authorize the application. Once connected, the Kognitos agent will have access to your Google Tasks while keeping your credentials secure. ## Actions The following actions are available in the **Google Tasks** integration: ### 1. Clear completed tasks from google tasks Clear all completed tasks from a Google Tasks task list. ### 2. Complete a task in google tasks Mark a task as completed in Google Tasks. ### 3. Create a task list in google tasks Create a new task list in Google Tasks. ### 4. Create a task in google tasks Create a new task in a Google Tasks task list. ### 5. Delete a task from google tasks Delete a task from a Google Tasks task list. ### 6. Delete a task list from google tasks Delete a task list from Google Tasks. ### 7. Get a task from google tasks Get a specific task from Google Tasks by its identifier. ### 8. Get some task lists from google tasks Get all task lists from Google Tasks. ### 9. Get some tasks from google tasks Get tasks from a Google Tasks task list. ### 10. Move a task in google tasks Move a task to a different position in its task list. ### 11. Update a task in google tasks Update an existing task in Google Tasks. ## Concepts ### Google task A Google Tasks task. | Field Name | Description | Type | | --------------- | ------------------------------------------------------ | ------------------- | | `title` | The title of the task. | `text` | | `id` | The task identifier. | `optional[text]` | | `notes` | Notes describing the task. | `optional[text]` | | `status` | The status of the task ("needsAction" or "completed"). | `optional[text]` | | `due` | The due date of the task (RFC 3339 timestamp). | `optional[text]` | | `completed` | The completion date of the task (RFC 3339 timestamp). | `optional[text]` | | `parent` | The parent task identifier (for subtasks). | `optional[text]` | | `position` | The position among sibling tasks. | `optional[text]` | | `updated` | The last modification time. | `optional[text]` | | `web_view_link` | An absolute link to the task in Google Tasks Web UI. | `optional[text]` | | `deleted` | Whether the task has been deleted. | `optional[boolean]` | | `hidden` | Whether the task is hidden. | `optional[boolean]` | ### Google task list A Google Tasks task list. | Field Name | Description | Type | | ---------- | -------------------------------------------- | ---------------- | | `id` | The task list identifier. | `text` | | `title` | The title of the task list. | `text` | | `updated` | The last modification time of the task list. | `optional[text]` | # HTTP Overview of the HTTP integration. {% hint style="info" %} The following documentation is for **HTTP v1.8.0**. {% endhint %} ## Overview HTTP integration provides fundamental web communication capabilities for API interactions and web service calls. This integration supports GET, POST, PUT, DELETE, and other HTTP methods for seamless API integration. Enable your workflows to communicate with any REST API or web service. ## Setup The following integrations need to be connected to your Kognitos workspace: * **HTTP** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using API Key Connect to the HTTP server using an API key. The API key will be sent as a x-api-key header in every request. | Label | Description | Type | | ------- | ------------------ | ----------- | | API Key | The API key value. | `sensitive` | ### Connect using Username and Password Connect to the HTTP server using basic authentication. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | Label | Description | Type | | -------- | -------------------------------------- | ----------- | | Username | The username for basic authentication. | `text` | | Password | The password for basic authentication. | `sensitive` | ### Connect using Token URL, Client ID and Client Secret Connect to the HTTP server using client credentials method. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | Label | Description | Type | | ------------- | ----------------------------------------- | ----------- | | Token URL | The token URL for client credentials. | `text` | | Client ID | The client ID for client credentials. | `text` | | Client Secret | The client secret for client credentials. | `sensitive` | ### Connect using Username and Password Connect to the HTTP server using digest authentication. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | Label | Description | Type | | -------- | --------------------------------------- | ----------- | | Username | The username for digest authentication. | `text` | | Password | The password for digest authentication. | `sensitive` | ### Connect using Token URL, Username, Password, Client ID and Client Secret Connect to the HTTP server using password grant method. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | Label | Description | Type | | ------------- | ------------------------------------- | ----------- | | Token URL | The token URL for password grant. | `text` | | Username | The username for password grant. | `text` | | Password | The password for password grant. | `sensitive` | | Client ID | The client ID for password grant. | `text` | | Client Secret | The client secret for password grant. | `sensitive` | ## Actions The following actions are available in the **HTTP** integration: ### 1. Delete a url Make a DELETE request to the specified url. ### 2. Head a url Make a HEAD request to the specified url. ### 3. Patch payload on a url Make a PATCH request to the specified url. ### 4. Post payload to a url Make a POST request to the specified url. ### 5. Put payload on a url Make a PUT request to the specified url. ### 6. Retrieve a url Make a GET request to the specified url. # Intelligent Document Processing (IDP) Overview of the Intelligent Document Processing (IDP) integration. {% hint style="info" %} The following documentation is for **Intelligent Document Processing (IDP) v4.15.11**. {% endhint %} ## Overview Intelligent Document Processing (IDP) extracts structured data from documents using AI. This integration enables automated document analysis, data extraction, and intelligent processing workflows. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Intelligent Document Processing (IDP)** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Credentials ### 1. Anthropic API Key Follow these steps to obtain your **Anthropic API key**: {% stepper %} {% step %} **Log in to the Anthropic Console** Go to the [**Anthropic Console**](https://console.anthropic.com) and log in with your credentials. {% endstep %} {% step %} **Navigate to API Keys** Go to **Settings** > **API Keys**. Then click **+ Create Key** in the top right. {% endstep %} {% step %} **Configuration** Select a workspace and give your key a descriptive name (e.g., "Development Key" or "Production App"). Then, click **Add** to generate your API key. {% endstep %} {% step %} **Copy and Store Your Key** Copy your API key immediately and store it securely. You won't be able to view it again after closing the dialog. {% endstep %} {% endstepper %} ### 2. OpenAI API Key Follow these steps to obtain your **OpenAI API key**: {% stepper %} {% step %} **Log In to OpenAI** Navigate to the [OpenAI Platform](https://auth.openai.com/log-in) and log in with your credentials. {% endstep %} {% step %} **API Keys** Open **Account Settings**, then navigate to [**API Keys**](https://platform.openai.com/account/api-keys)**.** {% endstep %} {% step %} **Generate a New API Key** Click **Create new secret key**. Copy the key immediately — it will only be shown once. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using API Key Connect to Anthropic API for document processing. | Label | Description | Type | | ------- | --------------------- | ----------- | | API Key | The Anthropic API key | `sensitive` | ### Connect using Service Account Credentials and Region Connect to Google Vertex AI (Gemini) API for document processing. | Label | Description | Type | | --------------------------- | ----------------------------------------------------- | ----------- | | Service Account Credentials | The Google service account credentials JSON as string | `sensitive` | | Region | The Google Cloud region | `text` | ### Connect using API Key Connect to OpenAI API for document processing. | Label | Description | Type | | ------- | ------------------ | ----------- | | API Key | The OpenAI API key | `sensitive` | ## Actions The following actions are available in the **Intelligent Document Processing (IDP)** integration: ### 1. Analyze a thing Analyze a document to extract its structure and content. ### 2. Classify a thing Classify a document against user-defined topics or rules. ### 3. Extract data from a thing Extract data from a document using field specifications. ### 4. Extract data from the documents Extract data from multiple documents in a single LLM call. ### 5. Extract pages from a thing Extract specified pages from a document. ### 6. Extract subdocument from a thing Extract a subdocument from a document based on page numbers or markers. ### 7. Extract subdocuments from a thing Extract subdocuments from a document based on markers or fixed size with overlap. ### 8. Extract table from a thing Extract table from a document using field specifications. ### 9. Merge pages into a document Merge multiple page documents into a single consolidated document. ### 10. Merge subdocuments into a document Merge multiple subdocuments into a single consolidated document. ### 11. Read content from a thing Read/extract text content from a document. ## Concepts ### Document analysis specification Input for document analysis (schema-free extraction).All fields are optional. | Field Name | Description | Type | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `analysis_mode` | \[Optional, default: "single\_pass"] Analysis mode. - "single\_pass": Sequential per-page extraction (simplest) - "parallel": Parallel extraction with smart deduplication - "plan\_based": Plan-based extraction (best for complex docs) | `optional[text]` | | `verify` | \[Optional, default: False] If True, performs cross-model verification to detect hallucinations. | `optional[boolean]` | | `verification_strictness` | \[Optional, default: "high"] Strictness level for verification. Options: "high", "moderate", "low". | `optional[text]` | | `dpi` | \[Optional, default: 150] DPI for image processing. | `optional[number?` or `text]` | | `confidence_threshold` | \[Optional, default: 0] Minimum confidence score (0-100) for extracted elements. Behavior: - When set to 0 (default): No threshold checking. All elements are returned regardless of confidence. Caller can inspect the `confidence` attribute on individual entities, key\_value\_pairs, and tables to decide how to handle low-confidence data. - When set to 1-100: Acts as a hard limit. If ANY element (entity, key-value pair, or table) has confidence below this threshold, raises AnalysisError. The exception contains: - `analysis`: The full DocumentAnalysis result (still usable) - `low_confidence_elements`: List of elements that failed - `threshold`: The threshold value that was not met Example: Set confidence\_threshold=80 to fail if any element has confidence below 80. Catch AnalysisError to access both the full result and the list of problematic elements. | `optional[number]` | ### Idp document analysis Complete analysis of a document.This is the output of schema-free document analysis, containing all detected elements including entities, tables, forms, and structure. All elements have a consistent structure with: - element\_type: For UI discrimination after serialization - page\_number: Page where element was found (1-indexed) - bounding\_box: Optional location on page - confidence: Optional confidence score (0-100) | Field Name | Description | Type | | ----------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------- | | `result_type` | Top-level discriminator for API response type. | `optional[text]` | | `document_type` | The type of document (e.g., invoice, receipt, form). | `optional[text]` | | `document_title` | The title of the document if detected. | `optional[text]` | | `source` | The source file name or identifier. | `optional[text]` | | [`key_value_pairs`](#key_value_pairs-idp-document-analysis) | List of key-value pairs extracted from the document. | `optional[list of json]` | | [`tables`](#idp-extracted-table) | List of tables detected in the document. | `optional[list of idp extracted table]` | | [`forms`](#forms-idp-document-analysis) | List of forms detected in the document. | `optional[list of json]` | | [`entities`](#entities-idp-document-analysis) | List of named entities extracted from the document. | `optional[list of json]` | | [`text_blocks`](#text_blocks-idp-document-analysis) | List of text blocks/paragraphs in the document. | `optional[list of json]` | | [`lists`](#lists-idp-document-analysis) | List of bulleted or numbered lists in the document. | `optional[list of json]` | | `full_text` | Full text content from markdown normalization. | `optional[text]` | | `confidence` | Overall confidence score for the analysis (0-100). | `optional[number]` | | `verified` | Whether the analysis has been verified. | `optional[boolean]` | | `hallucinations_detected` | Whether hallucinations were detected during verification. | `optional[boolean]` | | `analysis_mode` | The analysis mode used (single\_pass, parallel, or plan\_based). | `optional[text]` | | [`metrics`](#metrics-idp-document-analysis) | Document processing metrics (num\_pages, etc.). | `optional[json]` | ### Idp extracted table A detected table in the document.This class is returned by both extract\_table\_from\_thing (directly) and analyze\_thing (as part of DocumentAnalysis.tables). | Field Name | Description | Type | | --------------------------------------------------- | --------------------------------------------------------- | ------------------------ | | `element_type` | Always "table" regardless of which procedure produced it. | `optional[text]` | | `page_number` | Page number where table was found (1-indexed). | `optional[number]` | | [`bounding_box`](#bounding_box-idp-extracted-table) | Location of table on the page. | `optional[json]` | | `confidence` | Confidence score (0-100). | `optional[number]` | | `is_handwritten` | Whether the table appears to be handwritten. | `optional[boolean]` | | `title` | Table title/caption. | `optional[text]` | | `headers` | Column headers if detected. | `optional[list of text]` | | `rows` | Table rows (list of cell values). | `optional[list of text]` | | `num_rows` | Number of rows. | `optional[number]` | | `num_cols` | Number of columns. | `optional[number]` | | `arrow_table` | PyArrow Table representation of the data. | `optional[table?]` | | [`verification`](#verification-idp-extracted-table) | Verification result if verify=True was used. | `optional[json]` | ### Idp classification input Input for document classification.All fields are optional. At least one of topics, prompt, or classification\_rules (on procedure) must be provided. | Field Name | Description | Type | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | [`topics`](#idp-classification-topic) | \[Optional, default: None] List of ClassificationTopic objects to classify the document against. Highest priority if provided. | `optional[list of idp classification topic]` | | `prompt` | \[Optional, default: None] Classification instructions or context. If no topics provided, topics will be extracted from this prompt. Example: "Is this an invoice or a receipt?" | `optional[text]` | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `include_reasoning` | \[Optional, default: True] Whether to include reasoning explanation for each classification decision. | `optional[boolean]` | | `confidence_threshold` | \[Optional, default: 50] Minimum confidence score (0-100) to consider a topic as matched. | `optional[number]` | ### Idp classification topic A topic to classify the document against.Topics define what the classification should look for in a document. They can be simple labels or detailed criteria for the LLM to evaluate. | Field Name | Description | Type | | ------------- | ----------------------------------------------------- | ---------------- | | `name` | The topic name (e.g., "Contains PII", "Is Invoice"). | `optional[text]` | | `description` | Optional description to help understand the topic. | `optional[text]` | | `criteria` | Optional specific criteria for evaluating this topic. | `optional[text]` | ### Idp classification result Complete classification result for a document.Contains classification results for all evaluated topics, with an overall summary and confidence score. | Field Name | Description | Type | | ----------------------------------------------- | -------------------------------------------------------- | -------------------------------------------- | | `result_type` | Top-level API response discriminator. | `optional[text]` | | `source` | Source document name or identifier. | `optional[text]` | | [`classifications`](#idp-topic-classification) | List of classification results for each topic. | `optional[list of idp topic classification]` | | `summary` | Overall summary of the classification results. | `optional[text]` | | `confidence` | Overall confidence score (average across topics, 0-100). | `optional[number]` | | `processing_time_ms` | Time taken to process the classification. | `optional[number]` | | [`metrics`](#metrics-idp-classification-result) | Document processing metrics (num\_pages, etc.). | `optional[json]` | ### Idp topic classification Classification result for a single topic.Represents whether a document matches a specific topic, with confidence scoring and optional reasoning. | Field Name | Description | Type | | -------------- | ----------------------------------------------------- | ------------------- | | `element_type` | Discriminator for this element type in API responses. | `optional[text]` | | `topic` | The topic name that was evaluated. | `optional[text]` | | `matches` | Whether the document matches this topic. | `optional[boolean]` | | `confidence` | Confidence score (0-100) for this classification. | `optional[number]` | | `reasoning` | Explanation for why this classification was made. | `optional[text]` | ### Field extraction specification Input for data extraction from documents.Specify extraction requirements using either fields or prompt (not both). | Field Name | Description | Type | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | [`fields`](#fields-field-extraction-specification) | \[Required, one of] List of ExtractField objects defining what to extract from the document. | `optional[list of json]` | | `prompt` | \[Required, one of] Natural language description of what to extract. The LLM will parse this into fields automatically. Example: "Extract the invoice number, total amount, and vendor" | `optional[text]` | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `common_default_value` | \[Optional, default: ""] Default value to use for all fields if no specific default is provided. | `optional[text]` | | `dpi` | \[Optional, default: 150] DPI for image processing. | `optional[number?` or `text]` | | `confidence_threshold` | \[Optional, default: 90] Minimum confidence score (0-100). Fields below this threshold cause ExtractionError. | `optional[number]` | | `generate_overlay` | \[Optional, default: False] If True, generates an annotated PDF with bounding boxes around extracted fields. | `optional[boolean]` | | `reconcile_locations` | \[Optional, default: True] If True, matches LLM-extracted boxes with precise PDF text locations for digital PDFs. Falls back to LLM locations for scanned documents. | `optional[boolean]` | | `verify` | \[Optional, default: False] If True, performs cross-model verification to detect hallucinations and validate extracted values exist in the source document. | `optional[boolean]` | | `verification_strictness` | \[Optional, default: "high"] Strictness level for verification. Options: - "high": Zero tolerance, cell-by-cell exact matching - "moderate": Allows formatting differences - "low": Only flags clear hallucinations | `optional[text]` | | `raise_exception` | \[Optional, default: True] If True, raises ExtractionError when fields are missing or have low confidence. If False, returns partial results. | `optional[boolean]` | | `business_rules` | \[Optional, default: None] File (.txt, .md, .docx) containing extraction guidelines to include in the LLM prompt. | `optional[file]` | ### Extraction result Wrapper for extraction results providing self-describing API response.This class wraps the list of extracted fields to provide a consistent, self-describing response format that matches the pattern used by DocumentAnalysis from analyze\_thing. The UI can use `result_type` to determine how to render the response: - "extraction\_result" -> render as field list - "document\_analysis" -> render as structured analysis | Field Name | Description | Type | | --------------------------------------- | ----------------------------------------------------------- | ------------------------ | | `result_type` | Type discriminator for UI rendering ("extraction\_result"). | `optional[text]` | | [`fields`](#document-field) | List of extracted field results. | `list of document field` | | `document` | Primary document filename (for single-doc extraction). | `optional[text]` | | `document_count` | Number of documents processed (for multi-doc). | `optional[number]` | | `confidence` | Average confidence across all fields (0-100). | `optional[number]` | | [`metrics`](#metrics-extraction-result) | Document processing metrics (num\_pages, etc.). | `optional[json]` | ### Document field A dataclass representing an extraction field result.This class defines the structure for field results of data extraction, including the field name, extracted values, confidence, document source, and location. It shares common attributes with KeyValuePair from analysis for consistent API responses. Common attributes with analysis models: - element\_type: Type discriminator for UI rendering - page\_number: 1-indexed page number - bounding\_box: Location on page (BoundingBox format) - confidence: Confidence score (0-100) - verification: Validation result Extraction-specific attributes: - name: Field name (equivalent to 'key' in KeyValuePair) - values: List of extracted values - document: Source document reference - document\_index: For multi-document extraction | Field Name | Description | Type | | ---------------------------------------------- | ----------------------------------------------------------- | -------------------------------- | | `element_type` | Type of element for UI discrimination ("extracted\_field"). | `optional[text]` | | `name` | The name of the extraction field. | `optional[text]` | | `values` | List of extracted values for the field. | `optional[list of list of any?]` | | `document` | Full document reference where the value was found. | `optional[text]` | | `document_index` | 0-based index of the document (multi-document only). | `optional[number]` | | `page_number` | 1-indexed page number where the value was found. | `optional[number]` | | [`bounding_box`](#bounding_box-document-field) | Location on page using unified BoundingBox format. | `optional[json]` | | `confidence` | Confidence score (0-100). | `optional[number]` | | [`verification`](#verification-document-field) | Verification result from cross-model validation. | `optional[json]` | ### Page extraction specification Input for extracting specific pages from a document.All fields are optional. | Field Name | Description | Type | | ------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `start_page` | \[Optional, default: first page] First page to extract (1-based index). | `optional[number]` | | `end_page` | \[Optional, default: last page] Last page to extract (1-based index). | `optional[number]` | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `dpi` | \[Optional, default: 150] DPI for image processing. | `optional[number?` or `text]` | ### Page extraction result Result of extracting pages from a document. | Field Name | Description | Type | | -------------------------------------------- | ----------------------------------------------------------- | ---------------- | | `result_type` | Type discriminator for API response handling. | `optional[text]` | | [`pages`](#list-of-file) | List of extracted page documents as IO objects. | `list of file` | | `source_document` | Reference to the source document. | `optional[text]` | | [`metrics`](#metrics-page-extraction-result) | Processing metrics including page count of source document. | `optional[json]` | ### Subdocument extraction specification Input for extracting a subdocument based on pages or markers.All fields are optional. Use page numbers OR markers, not both. | Field Name | Description | Type | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `start_page` | \[Optional, default: first page] First page of the subdocument (1-based index). | `optional[number]` | | `end_page` | \[Optional, default: last page] Last page of the subdocument (1-based index). | `optional[number]` | | `start_page_marker` | \[Optional, default: None] Text/logic to find the starting page. Example: "Page containing 'Introduction'" | `optional[text]` | | `end_page_marker` | \[Optional, default: None] Text/logic to find the ending page (inclusive). | `optional[text]` | | `excluded_end_page_marker` | \[Optional, default: None] Text/logic to find the ending page (exclusive - page before this marker). | `optional[text]` | | `subdocument_size` | \[Optional, default: None] Maximum number of pages in the subdocument. Cannot be used with end markers. | `optional[number]` | | `dpi` | \[Optional, default: 150] DPI for image processing. | `optional[number?` or `text]` | ### Subdocument extraction result Result of extracting a subdocument from a document. | Field Name | Description | Type | | --------------------------------------------------- | ----------------------------------------------------------- | ------------------ | | `result_type` | Type discriminator for API response handling. | `optional[text]` | | `subdocument` | The extracted subdocument as an IO object. | `file` | | `source_document` | Reference to the source document. | `optional[text]` | | `start_page` | Starting page number (1-based) of the subdocument. | `optional[number]` | | `end_page` | Ending page number (1-based) of the subdocument. | `optional[number]` | | [`metrics`](#metrics-subdocument-extraction-result) | Processing metrics including page count of source document. | `optional[json]` | ### Subdocuments extraction specification Input for extracting multiple subdocuments using markers or fixed size.All fields are optional. Supports two extraction strategies: 1. Marker-based: Split at pages matching a text pattern 2. Fixed-size: Split into N-page chunks with optional overlap | Field Name | Description | Type | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `start_page` | \[Optional, default: first page] First page to process (1-based index). | `optional[number]` | | `end_page` | \[Optional, default: last page] Last page to process (1-based index). | `optional[number]` | | `start_page_marker` | \[Optional, default: None] Text/logic to find where each subdocument starts. Example: "INVOICE NUMBER" | `optional[text]` | | `end_page_marker` | \[Optional, default: None] Text/logic to find where each subdocument ends (inclusive). Requires start\_page\_marker. | `optional[text]` | | `excluded_end_page_marker` | \[Optional, default: None] Text/logic to find where each subdocument ends (exclusive). Requires start\_page\_marker. | `optional[text]` | | `subdocument_size` | \[Optional, default: None] Fixed number of pages per subdocument for chunking mode. | `optional[number]` | | `subdocument_overlap_size` | \[Optional, default: None] Number of overlapping pages between consecutive chunks. Requires subdocument\_size. | `optional[number]` | | `dpi` | \[Optional, default: 150] DPI for image processing. | `optional[number?` or `text]` | ### Subdocuments extraction result Result of extracting multiple subdocuments from a document. | Field Name | Description | Type | | ---------------------------------------------------- | ----------------------------------------------------------- | ---------------- | | `result_type` | Type discriminator for API response handling. | `optional[text]` | | [`subdocuments`](#list-of-file) | List of extracted subdocuments as IO objects. | `list of file` | | `source_document` | Reference to the source document. | `optional[text]` | | [`metrics`](#metrics-subdocuments-extraction-result) | Processing metrics including page count of source document. | `optional[json]` | ### Table extraction specification Input for table extraction from documents. | Field Name | Description | Type | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | | `description` | \[Required] Description of the table to extract. Example: "Extract the Previous Employment History table" | `text` | | `llm_model` | \[Optional, default: provider default] LLM model to use. Provider defaults: gemini-2.5-pro, gpt-4o, claude-sonnet-4-5. | `optional[text]` | | `dpi` | \[Optional, default: 150] DPI for image processing. | `optional[number?` or `text]` | | `confidence_threshold` | \[Optional, default: 0] Minimum confidence score (0-100) for the extracted table. If below threshold, raises ExtractionError. Set to 0 to disable threshold checking. | `optional[number]` | | `raise_exception` | \[Optional, default: True] If True, raises ExtractionError when confidence is below threshold. If False, returns the result with low confidence instead of raising. | `optional[boolean]` | | `verify` | \[Optional, default: False] If True, performs cross-model verification to detect hallucinations and validate extracted table data exists in the source document. | `optional[boolean]` | | `verification_strictness` | \[Optional, default: "high"] Strictness level for verification. Options: - "high": Zero tolerance, cell-by-cell exact matching - "moderate": Allows formatting differences - "low": Only flags clear hallucinations | `optional[text]` | ### Idp table extraction result Wrapper for table extraction results.This provides a consistent API response format for extract\_table\_from\_thing, with a result\_type discriminator for UI rendering. | Field Name | Description | Type | | ------------------------------------------------- | ----------------------------------------------- | ------------------------------- | | `result_type` | Top-level discriminator ("table\_extraction"). | `optional[text]` | | [`table`](#idp-extracted-table) | The extracted table. | `optional[idp extracted table]` | | `document` | Source document filename. | `optional[text]` | | `confidence` | Confidence score (0-100). | `optional[number]` | | [`metrics`](#metrics-idp-table-extraction-result) | Document processing metrics (num\_pages, etc.). | `optional[json]` | ### Merge document result Result of merging pages or subdocuments into a document. | Field Name | Description | Type | | ------------------------------------------- | ----------------------------------------------------------- | ------------------ | | `result_type` | Type discriminator for API response handling. | `optional[text]` | | `document` | The merged document as an IO object. | `file` | | `document_name` | Name of the merged document. | `optional[text]` | | `source_count` | Number of source pages/subdocuments that were merged. | `optional[number]` | | [`metrics`](#metrics-merge-document-result) | Processing metrics including page count of merged document. | `optional[json]` | ### Read content result Result of reading/extracting text content from a document. | Field Name | Description | Type | | ----------------------------------------- | ----------------------------------------------------------- | ---------------- | | `result_type` | Type discriminator for API response handling. | `optional[text]` | | `content` | The extracted text content. | `optional[text]` | | `source_document` | Reference to the source document. | `optional[text]` | | [`metrics`](#metrics-read-content-result) | Processing metrics including page count of source document. | `optional[json]` | #### Concept attribute specifications **key\_value\_pairs (idp document analysis)** | Name | Type | | ---------------- | ----------------------------- | | `element_type` | `optional[text]` | | `page_number` | `optional[number]` | | `bounding_box` | `optional[json]` | | `confidence` | `optional[number]` | | `is_handwritten` | `optional[boolean]` | | `key` | `optional[text]` | | `value` | `number?]` or `optional[text` | | `verification` | `optional[json]` | **forms (idp document analysis)** | Name | Type | | ---------------- | ------------------- | | `element_type` | `optional[text]` | | `page_number` | `optional[number]` | | `bounding_box` | `optional[json]` | | `confidence` | `optional[number]` | | `is_handwritten` | `optional[boolean]` | | `title` | `optional[text]` | | `fields` | `optional[json]` | **entities (idp document analysis)** | Name | Type | | ------------------ | ------------------- | | `element_type` | `optional[text]` | | `page_number` | `optional[number]` | | `bounding_box` | `optional[json]` | | `confidence` | `optional[number]` | | `is_handwritten` | `optional[boolean]` | | `entity_type` | `optional[text]` | | `text` | `optional[text]` | | `normalized_value` | `optional[any?]` | | `context` | `optional[text]` | | `verification` | `optional[json]` | **text\_blocks (idp document analysis)** | Name | Type | | ---------------- | ------------------- | | `element_type` | `optional[text]` | | `page_number` | `optional[number]` | | `bounding_box` | `optional[json]` | | `confidence` | `optional[number]` | | `is_handwritten` | `optional[boolean]` | | `content` | `optional[text]` | | `style` | `optional[text]` | | `level` | `optional[number]` | | `items` | `optional[text]` | | `list_type` | `optional[text]` | **lists (idp document analysis)** | Name | Type | | ---------------- | ------------------- | | `element_type` | `optional[text]` | | `page_number` | `optional[number]` | | `bounding_box` | `optional[json]` | | `confidence` | `optional[number]` | | `is_handwritten` | `optional[boolean]` | | `list_type` | `optional[text]` | | `items` | `optional[text]` | **metrics (idp document analysis)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **bounding\_box (idp extracted table)** | Name | Type | | -------- | ------------------ | | `x` | `optional[number]` | | `y` | `optional[number]` | | `width` | `optional[number]` | | `height` | `optional[number]` | **verification (idp extracted table)** | Name | Type | | ------------------------- | ------------------- | | `is_valid` | `optional[boolean]` | | `adjusted_confidence` | `optional[number]` | | `value_found_in_document` | `optional[boolean]` | | `issues` | `optional[text]` | | `suggested_correction` | `optional[text]` | **metrics (idp classification result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **fields (field extraction specification)** | Name | Type | | --------------- | ---------------- | | `name` | `text` | | `format` | `optional[text]` | | `rule` | `optional[text]` | | `default_value` | `optional[any?]` | **metrics (extraction result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **bounding\_box (document field)** | Name | Type | | -------- | ------------------ | | `x` | `optional[number]` | | `y` | `optional[number]` | | `width` | `optional[number]` | | `height` | `optional[number]` | **verification (document field)** | Name | Type | | ------------------------- | ------------------- | | `is_valid` | `optional[boolean]` | | `adjusted_confidence` | `optional[number]` | | `value_found_in_document` | `optional[boolean]` | | `issues` | `optional[text]` | | `suggested_correction` | `optional[text]` | **metrics (page extraction result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **metrics (subdocument extraction result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **metrics (subdocuments extraction result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **metrics (idp table extraction result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **metrics (merge document result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | **metrics (read content result)** | Name | Type | | ----------- | ------------------ | | `num_pages` | `optional[number]` | # Jira Overview of the Jira integration. {% hint style="info" %} The following documentation is for **Jira v1.2.0**. {% endhint %} ## Overview Jira is Atlassian's project management and issue tracking platform. This integration lets you create, search, edit, assign, and delete Jira issues, and retrieve Jira labels directly from your Kognitos automations. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Jira** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### OAuth Authorization Code Best for personal accounts. Click Continue with Atlassian to sign in through Atlassian's secure authentication page and authorize the connection. ### Connect Using Email, Domain and API Token Connects to Jira using your Atlassian email and an API token. | Label | Description | Type | | --------- | ------------------------------------------------------------------------------------------------ | ----------- | | Email | Your Atlassian account email, the one you use to log in. Example: `john@company.com` | `text` | | Domain | Your Jira Cloud site domain (the host part of your Jira URL). Example: `mycompany.atlassian.net` | `text` | | API Token | An API token generated from your Atlassian account settings. | `sensitive` | {% hint style="info" %} To generate an API token, go to [**Atlassian API Tokens**](https://id.atlassian.com/manage-profile/security/api-tokens), click Create API token, give it a label, and copy the value. {% endhint %} ## Actions The following actions are available in the **Jira** integration: ### 1. Assign an issue Assigns a Jira issue to a user. Looks up the user by email and assigns the issue to them. ### 2. Create an issue Creates a new issue in a Jira project. You can specify the project key, summary, and issue type (defaults to "Task"). ### 3. Create multiple issues Creates multiple issues in a Jira project in a single operation. Each issue in the list needs at least a summary. ### 4. Delete an issue Permanently deletes an issue from Jira. This action cannot be undone. ### 5. Edit an issue Edits an existing issue in Jira. Compares the provided issue against its current state and updates only the fields that have changed. Supports updating summary, status, issue type, priority, and assignee. ### 6. Get labels Retrieves labels from Jira. ### 7. Search issues Searches for issues in Jira. If no filter is provided, returns all issues. Supports filtering by any Jira field: project, status, assignee, priority, issue type, summary, created, updated, labels, reporter, and resolution. ## Concepts ### Jira issue An issue in Jira. | Field Name | Description | Type | | ------------ | ----------------------------------------------- | ------ | | `id` | The unique identifier of the issue. | `text` | | `key` | The issue key (e.g., PROJ-123). | `text` | | `summary` | The summary/title of the issue. | `text` | | `status` | The current status of the issue. | `text` | | `issue_type` | The type of the issue (e.g., Bug, Story, Task). | `text` | | `priority` | The priority level of the issue. | `text` | | `assignee` | The display name of the assignee. | `text` | | `created` | The creation date of the issue. | `text` | | `updated` | The last updated date of the issue. | `text` | # Kafka Overview of the Kafka integration. {% hint style="info" %} The following documentation is for **Kafka v1.0.0**. {% endhint %} ## Overview on a Kafka cluster via the REST Proxy API (Karapace / Confluent). ## Setup The following integrations need to be connected to your Kognitos workspace: * **Kafka** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Basic Authentication Connect to Kafka using HTTP Basic Authentication. | Label | Description | Type | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | Base URL | The base URL of the Kafka REST Proxy (e.g. "" for Aiven, or "" for Confluent Cloud). | `text` | | Username | The username or API key for authentication (e.g. "avnadmin" for Aiven). | `text` | | Password | The password or API secret for authentication. | `sensitive` | #### Connect using Bearer Token Connect to Kafka using a Bearer token. | Label | Description | Type | | ------------ | ------------------------------------------------------------------------------------------------------------ | ----------- | | Base URL | The base URL of the Kafka REST Proxy (e.g. "" or ""). | `text` | | Bearer Token | The Bearer token for authentication. | `sensitive` | #### Connect using No Authentication Connect to Kafka without authentication. | Label | Description | Type | | -------- | ---------------------------------------------------------------------- | ------ | | Base URL | The base URL of the Kafka REST Proxy (e.g. ""). | `text` | ## Actions {% hint style="info" %} The available actions for **Kafka** are listed in the product UI on the integration page once you create a connection. {% endhint %} # Katana Overview of the Katana integration. {% hint style="info" %} The following documentation is for **Katana v2.0.0**. {% endhint %} ## Overview Katana is a comprehensive manufacturing resource planning (MRP) software designed for modern manufacturers. This integration enables automated inventory management, production scheduling, order processing, and supply chain optimization workflows. Streamline manufacturing operations and improve production efficiency through automated processes. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Katana** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using api key Connects to an API using the provided API key. | Label | Description | Type | | ------- | ------------------------------------- | ------ | | api key | The API key to be used for connecting | `text` | ## Actions The following actions are available in the **Katana** integration: ### 1. Retrieve some customers Fetch the customers with optional filtering. ### 2. Retrieve some purchase orders Fetch the purchase orders with optional filtering. ### 3. Retrieve some sales orders Fetch the sales orders with optional filtering. ### 4. Update a sales order Update an existing sales order. ## Concepts ### Katana customer Customer represents a customer within the Katana system, serving as a comprehensive record of customer information, contact details, and associated addresses. It provides essential information to manage customer relationships and process orders. | Field Name | Description | Type | | ----------------------------------------- | ------------------------------------------------------------------------ | ------------------------ | | `id` | Unique identifier for the customer. | `text` | | `name` | Customer's full name or business name. | `text` | | [`addresses`](#addresses-katana-customer) | An array of shipping and billing addresses associated with the customer. | `optional[list of json]` | | `first_name` | Customer's first name. | `optional[text]` | | `last_name` | Customer's last name. | `optional[text]` | | `company` | Company name associated with the customer. | `optional[text]` | | `email` | Customer's email address for communication. | `optional[text]` | | `phone` | Customer's phone number for contact. | `optional[text]` | | `comment` | Additional comments or notes about the customer. | `optional[text]` | | `currency` | Default currency code used for the customer's transactions. | `optional[text]` | | `reference_id` | External reference identifier for integration purposes. | `optional[text]` | | `category` | Customer category or classification for grouping. | `optional[text]` | | `discount_rate` | Default discount rate applied to the customer's orders. | `optional[number]` | | `created_at` | The timestamp when the customer was created. | `optional[datetime]` | | `updated_at` | The timestamp when the customer was last updated. | `optional[datetime]` | | `default_billing_id` | ID of the default billing address from the addresses array. | `optional[text]` | | `default_shipping_id` | ID of the default shipping address from the addresses array. | `optional[text]` | ### Katana purchase order PurchaseOrder represents a supplier order within the Katana system, serving as a comprehensive record of all order details, receiving status, and associated metadata. It provides essential information to track and manage supplier orders throughout their lifecycle. | Field Name | Description | Type | | ------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------ | | `id` | Unique identifier for the object. | `text` | | `order_no` | A unique, identifying string used in the UI and controlled by the user. | `text` | | [`purchase_order_rows`](#purchase_order_rows-katana-purchase-order) | An array of purchase order rows. | `optional[list of json]` | | `status` | Status of the order. | `optional[text]` | | `billing_status` | Status of generating the bill through accounting integration. | `optional[text]` | | `last_document_status` | Status of the last e-mail sent from (O)PO card. | `optional[text]` | | `entity_type` | Either "regular" or "outsourced", depending on the purchase order type. | `optional[text]` | | `supplier_id` | ID of the supplier who this order belongs to. | `optional[text]` | | `currency` | Currency of the purchase order. | `optional[text]` | | `expected_arrival_date` | The timestamp when the items are expected to arrive. | `optional[datetime]` | | `order_created_date` | The timestamp of creating the document. | `optional[datetime]` | | `location_id` | The ID of the location to which items are received. | `optional[text]` | | `total` | The total value of the order (including taxes) in purchase order currency. | `optional[number]` | | `total_in_base_currency` | The total value of the order (including taxes) in base currency. | `optional[number]` | | `created_at` | The timestamp when the purchase order was created. | `optional[datetime]` | | `updated_at` | The timestamp when the purchase order was last updated. | `optional[datetime]` | | `additional_info` | Internal comments, links to external files, additional instructions. | `optional[text]` | | `ingredient_availability` | Status of ingredients for outsourced purchase orders. | `optional[text]` | | `ingredient_expected_date` | Latest date for required ingredients on outsourced orders. | `optional[datetime]` | | `tracking_location_id` | Location where ingredients are processed for outsourced orders. | `optional[text]` | ### Katana sales order SalesOrder represents a customer order within the Katana system, serving as a comprehensive record of all order details, fulfillment status, and associated metadata. It provides essential information to track and manage customer orders throughout their lifecycle. | Field Name | Description | Type | | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------ | | `id` | Unique identifier for the object. | `text` | | `order_no` | A unique, identifying string used in the UI and controlled by the user. | `text` | | [`sales_order_rows`](#sales_order_rows-katana-sales-order) | An array of sales order rows. | `optional[list of json]` | | [`addresses`](#addresses-katana-sales-order) | An array of shipping and billing addresses. | `optional[list of json]` | | `customer_id` | ID of the customer who this order belongs to. | `optional[text]` | | `source` | Indication of whether the sales order was created manually, by API or imported from somewhere else. | `optional[text]` | | `location_id` | ID of the location from which the order is shipped by default. | `optional[text]` | | `status` | Status of the order. | `optional[text]` | | `currency` | Currency of the sales order. | `optional[text]` | | `invoicing_status` | Status of generating the invoice through accounting integration. | `optional[text]` | | `product_availability` | Stock status for the products required by the sales order. | `optional[text]` | | `ingredient_availability` | Stock status for ingredients required to produce the products. | `optional[text]` | | `production_status` | Production status of the manufacturing order. | `optional[text]` | | `billing_address_id` | The ID of the billing address of the sales order. | `optional[text]` | | `shipping_address_id` | The ID of the shipping address of the sales order. | `optional[text]` | | `order_created_date` | The timestamp of creating the document. | `optional[datetime]` | | `delivery_date` | A timestamp when the items are required to be delivered to the customer. | `optional[datetime]` | | `conversion_date` | The date of the conversion rate used. | `optional[datetime]` | | `conversion_rate` | Currency rate used to convert from sales order currency into factory base currency. | `optional[number]` | | `created_at` | The timestamp when the sales order was created. | `optional[datetime]` | | `updated_at` | The timestamp when the sales order was last updated. | `optional[datetime]` | | `total_in_base_currency` | The total value of the order (including taxes) in base currency. | `optional[number]` | | `total` | The total value of the order (including taxes) in sales order currency. | `optional[number]` | | `picked_date` | The timestamp when delivery status was marked as "PACKED" or "DELIVERED". | `optional[datetime]` | | `additional_info` | Internal comments, links to external files, additional instructions. | `optional[text]` | | `customer_ref` | An identifier to reference the customer associated with the sales order. | `optional[text]` | | `ecommerce_order_type` | Name of the ecommerce platform if imported from one. | `optional[text]` | | `ecommerce_store_name` | Name of the ecommerce store if imported from ecommerce platform. | `optional[text]` | | `ecommerce_order_id` | ID of the order in the source system if imported. | `optional[text]` | | `product_expected_date` | Latest date of manufacturing/purchasing deadline for required products. | `optional[datetime]` | | `ingredient_expected_date` | Latest date of manufacturing/purchasing deadline for required ingredients. | `optional[datetime]` | | `tracking_number` | Deprecated - use tracking\_number from sales order fulfillment instead. | `optional[text]` | | `tracking_number_url` | Deprecated - use tracking\_number\_url from sales order fulfillment instead. | `optional[text]` | #### Concept attribute specifications **addresses (katana customer)** | Name | Type | | ------------- | -------------------- | | `id` | `text` | | `customer_id` | `optional[text]` | | `entity_type` | `optional[text]` | | `default` | `optional[boolean]` | | `first_name` | `optional[text]` | | `last_name` | `optional[text]` | | `company` | `optional[text]` | | `phone` | `optional[text]` | | `line_1` | `optional[text]` | | `line_2` | `optional[text]` | | `city` | `optional[text]` | | `state` | `optional[text]` | | `zip` | `optional[text]` | | `country` | `optional[text]` | | `created_at` | `optional[datetime]` | | `updated_at` | `optional[datetime]` | **purchase\_order\_rows (katana purchase order)** | Name | Type | | ------------------------------ | -------------------- | | `id` | `text` | | `variant_id` | `optional[text]` | | `quantity` | `optional[number]` | | `price_per_unit` | `optional[number]` | | `purchase_uom` | `optional[text]` | | `purchase_uom_conversion_rate` | `optional[number]` | | `total` | `optional[number]` | | `total_in_base_currency` | `optional[number]` | | `conversion_rate` | `optional[number]` | | `conversion_date` | `optional[datetime]` | | `created_at` | `optional[datetime]` | | `updated_at` | `optional[datetime]` | | `tax_rate_id` | `optional[text]` | | `batch_transactions` | `optional[json]` | | `received_date` | `optional[datetime]` | | `arrival_date` | `optional[datetime]` | **sales\_order\_rows (katana sales order)** | Name | Type | | --------------------------------- | -------------------- | | `id` | `text` | | `variant_id` | `optional[text]` | | `conversion_rate` | `optional[text]` | | `conversion_date` | `optional[datetime]` | | `created_at` | `optional[datetime]` | | `updated_at` | `optional[datetime]` | | `quantity` | `optional[number]` | | `price_per_unit` | `optional[number]` | | `price_per_unit_in_base_currency` | `optional[number]` | | `total_in_base_currency` | `optional[number]` | | `total` | `optional[number]` | | `tax_rate_id` | `optional[text]` | | `location_id` | `optional[text]` | | `product_availability` | `optional[text]` | | `product_expected_date` | `optional[datetime]` | | `cogs_value` | `optional[number]` | | `attributes` | `optional[json]` | | `batch_transactions` | `optional[json]` | | `serial_numbers` | `optional[text]` | | `linked_manufacturing_order_id` | `optional[text]` | **addresses (katana sales order)** | Name | Type | | ---------------- | -------------------- | | `id` | `text` | | `sales_order_id` | `optional[text]` | | `entity_type` | `optional[text]` | | `line_1` | `optional[text]` | | `city` | `optional[text]` | | `zip` | `optional[text]` | | `country` | `optional[text]` | | `created_at` | `optional[datetime]` | | `updated_at` | `optional[datetime]` | | `first_name` | `optional[text]` | | `last_name` | `optional[text]` | | `company` | `optional[text]` | | `phone` | `optional[text]` | | `line_2` | `optional[text]` | | `state` | `optional[text]` | # Linear Overview of the Linear integration. {% hint style="info" %} The following documentation is for **Linear v1.2.0**. {% endhint %} ## Overview Streamline your team's project management and issue tracking with Linear integration. Linear is a modern project management platform that helps teams organize work, track progress, and deliver projects efficiently. This integration enables you to seamlessly manage your Linear workspace directly through natural language commands. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Linear** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **Linear** integration: ### 1. Create an issue Create an issue in Linear. ### 2. Get the issues Fetch the issues matching the filters (if any). ### 3. Get the labels Fetch all available issue label names in the workspace. ### 4. Get the teams Fetch the teams matching the filters (if any). ### 5. Get the users from a team Get the users from a team. ## Concepts ### Linear team A team in Linear | Field Name | Description | Type | | ---------- | ----------------------------------- | ------ | | `id` | The unique identifier for the team. | `text` | | `name` | The name of the team. | `text` | | `key` | The short identifier for the team. | `text` | ### Linear user A user in Linear | Field Name | Description | Type | | ---------- | -------------------------------------------- | --------- | | `id` | The unique identifier for the user. | `text` | | `email` | The email address of the user. | `text` | | `name` | The name of the user. | `text` | | `is_me` | Whether this user is the authenticated user. | `boolean` | # Microsoft Excel Overview of the Excel (online) integration. {% hint style="info" %} The following documentation is for **Excel (online) v2.6.0**. {% endhint %} ## Overview Enables interacting with and managing Excel Online files and spreadsheets via the Microsoft Graph API. Excel offers powerful capabilities for data analysis, visualization, and automation, making it ideal for teams that need reliable, high-volume spreadsheet operations. This integration gives agents seamless access to worksheet management, bulk range and table updates, formulas, formatting, sorting, filtering, protection, pivot refresh, and recalculation for accurate, real-time data handling. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Excel (online)** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Client ID, Client Secret and Tenant ID Connect to the Microsoft Graph API using the provided client credentials. | Label | Description | Type | | ------------- | ------------------------------------------------------------ | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Client Secret | The client secret of the application registered in Azure AD. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | ### Connect using Client ID, Certificate and Tenant ID Connect to the Microsoft Graph API using certificate credentials. | Label | Description | Type | | ----------- | ------------------------------------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded X.509 certificate string containing both the certificate and private key. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | ### Connect using Client ID, Certificate, Private Key and Tenant ID Connect to the Microsoft Graph API using certificate and private key. | Label | Description | Type | | ----------- | -------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded certificate string. | `sensitive` | | Private Key | PEM-encoded private key string. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | ## Actions The following actions are available in the **Excel (online)** integration: ### 1. Clear all filters on the table Clear all filters on a table. ### 2. Clear the filter on the table's column Clear the filter on a specific table column. ### 3. Clear the worksheet range Delete the contents of a range of cells in an Excel worksheet. ### 4. Copy the sheet with a name Copy a worksheet's content to a new sheet in the same workbook. ### 5. Create a new sheet in the file Create a new worksheet in an Excel workbook. ### 6. Create a table on a worksheet range Create a table from a specified range of cells in an Excel worksheet. ### 7. Create a worksheet range in a sheet Create a range reference for a set of cells in an Excel worksheet, defined by start and end cell addresses. This does not modify the spreadsheet; it creates a local reference that can be used with other procedures to read, write, or clear data. ### 8. Create a workbook in a folder Create a new empty Excel workbook in a SharePoint or OneDrive folder. ### 9. Delete a column from the table Delete a column from a table in an Excel worksheet. ### 10. Delete a row from the table Delete a row from a table in an Excel worksheet. ### 11. Delete the sheet Delete a worksheet from an Excel workbook. ### 12. Filter the table's column by a filter value Apply a value-based filter to a table column. ### 13. Get the cell's color Get the background color of a cell in an Excel worksheet. ### 14. Get the cell's formula Get the formula of a cell in an Excel worksheet. ### 15. Get the cell's number format Get the number format string of a cell in an Excel worksheet. ### 16. Get the cell's value Get the value of a cell in an Excel worksheet. ### 17. Get the column count in a table Get the number of columns in a table in an Excel worksheet. ### 18. Get the column count in a worksheet range Get the number of columns in an Excel worksheet range. ### 19. Get the column's cells from the table Get the cells from a column in a table in an Excel worksheet. ### 20. Get the file's sheets Get the worksheets of an Excel file. ### 21. Get the following row range in a worksheet range Get a range representing the row immediately below the given range, spanning the same columns. Useful for appending data below an existing range or table. ### 22. Get the row count in a table Get the number of rows in a table in an Excel worksheet. ### 23. Get the row count in a worksheet range Get the number of rows in an Excel worksheet range. ### 24. Get the row's cells from the table Get the cells from a row in a table in an Excel worksheet. ### 25. Get the row's cells from the worksheet range Get the cells from a row in an Excel worksheet range. ### 26. Get the sheet's pivot tables Get the pivot tables from an Excel worksheet. ### 27. Get the sheet's protection status Get the protection status of a worksheet. ### 28. Get the sheet's tables Get the tables from an Excel worksheet. ### 29. Get the sheet's used range Get the used range of an Excel worksheet. ### 30. Get the worksheet range's rows Get the rows from a range in an Excel worksheet. ### 31. Get the worksheet range from the table Get the range of a table in an Excel worksheet. ### 32. Insert a new column in the table Insert a new column within a table in an Excel worksheet. ### 33. Insert a new row in the table Insert a new row in a table in an Excel worksheet. ### 34. Open a workbook at a url Open an Excel workbook by its SharePoint or OneDrive URL, returning its sheets. ### 35. Protect the sheet Protect a worksheet from editing. ### 36. Read the content from a table Read the contents of a table in an Excel worksheet. ### 37. Read the content from a worksheet range Read the contents of a range in an Excel worksheet. ### 38. Recalculate the workbook Force a full recalculation of all formulas in the workbook. ### 39. Refresh all pivot tables in the sheet Refresh all pivot tables in a worksheet. ### 40. Refresh the pivot table Refresh a specific pivot table. ### 41. Rename the sheet to a new name Rename a worksheet in an Excel workbook. ### 42. Retrieve the columns from the table Get the columns from a table in an Excel worksheet. ### 43. Retrieve the rows from the table Get the rows from a table in an Excel worksheet. ### 44. Set the cell's content to a value Update the value of a cell in an Excel worksheet. ### 45. Set the cell's formula to a formula value Update the formula of a cell in an Excel worksheet. ### 46. Set the cell's number format to a format string Set the number format of a cell in an Excel worksheet. ### 47. Set the worksheet range's number format to a format string Set a uniform number format on all cells in a range. ### 48. Sort the table by a column index Sort a table by a specified column. ### 49. Sort the worksheet range by a column index Sort a range by a specified column. ### 50. Unprotect the sheet Remove protection from a worksheet. ### 51. Write the content in a table Update the contents of an Excel table with new data. ### 52. Write the content in a worksheet range Update the contents of a range in an Excel worksheet. ## Concepts ### Excel table reference ExcelTableRef represents a reference to a table within an Excel worksheet, providing essential details to uniquely identify and interact with specific tables. This utility is used to facilitate data management, structured data handling, and integration within larger workflows. | Field Name | Description | Type | | ---------- | ------------------------------------------------------------ | ------ | | `id` | The unique identifier for the worksheet. | `text` | | `name` | The name of the worksheet. | `text` | | `drive_id` | The unique identifier for the drive containing the workbook. | `text` | | `file_id` | The unique identifier for the workbook. | `text` | | `sheet_id` | The unique identifier for the worksheet. | `text` | ### Excel column reference ExcelColumnRef represents a reference to a specific column within an Excel worksheet. It serves as a utility to uniquely identify and interact with data in a column, providing essential metadata that allows for efficient data manipulation and retrieval. | Field Name | Description | Type | | ---------- | ------------------------------------- | -------- | | `id` | The unique identifier for the column. | `text` | | `index` | The index of the column. | `number` | ### Excel range reference ExcelRangeRef represents a reference to a range of cells within an Excel worksheet. It provides detailed information about a contiguous set of cells and is designed for use in applications that require precise range-based operations, such as data extraction, modification, and analysis within spreadsheets. | Field Name | Description | Type | | --------------- | ------------------------------------------------------------ | ------------------- | | `drive_id` | The unique identifier for the drive containing the workbook. | `text` | | `file_id` | The unique identifier for the workbook. | `text` | | `sheet_id` | The unique identifier for the worksheet. | `text` | | `address` | The address of the range. | `text` | | `address_local` | The local address of the range. | `optional[text]` | | `cell_count` | The number of cells in the range. | `optional[number]` | | `column_count` | The number of columns in the range. | `optional[number]` | | `column_hidden` | Whether the columns in the range are hidden. | `optional[boolean]` | | `column_index` | The index of the first column in the range. | `optional[number]` | | `hidden` | Whether the range is hidden. | `optional[boolean]` | | `row_count` | The number of rows in the range. | `optional[number]` | | `row_hidden` | Whether the rows in the range are hidden. | `optional[boolean]` | | `row_index` | The index of the first row in the range. | `optional[number]` | ### Excel sheet reference ExcelSheetRef represents a reference to a worksheet within an Excel workbook, providing details to uniquely identify and interact with a specific sheet. It facilitates precise data manipulation and integration, useful for data processing, automated workflows, and integration across multiple files. | Field Name | Description | Type | | ---------- | ------------------------------------------------------------ | ------ | | `id` | The unique identifier for the worksheet. | `text` | | `name` | The name of the worksheet. | `text` | | `drive_id` | The unique identifier for the drive containing the workbook. | `text` | | `file_id` | The unique identifier for the workbook. | `text` | ### Sharepoint file reference A Sharepoint File Reference is a reference to a file in a SharePoint document library. | Field Name | Description | Type | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | | `id` | The unique identifier for the document library. | `optional[text]` | | `name` | The name of the document library. | `optional[text]` | | `web_url` | URL that either displays the resource in the browser (for Office file formats), or is a direct link to the file (for other formats). | `optional[text]` | | [`parent_reference`](#parent_reference-sharepoint-file-reference) | Parent information, if the item has a parent. | `optional[json]` | | `is_folder` | Boolean flag indicating whenever this item is a folder or not. | `optional[boolean]` | | `file_name` | The name of the file. Same as name. | `optional[text]` | ### Sharepoint folder reference A Sharepoint Folder Reference is a reference to a folder in a SharePoint document library. | Field Name | Description | Type | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | | `id` | The unique identifier for the document library. | `optional[text]` | | `name` | The name of the document library. | `optional[text]` | | `web_url` | URL that either displays the resource in the browser (for Office file formats), or is a direct link to the file (for other formats). | `optional[text]` | | [`parent_reference`](#parent_reference-sharepoint-folder-reference) | Parent information, if the item has a parent. | `optional[json]` | | `is_folder` | Boolean flag indicating whenever this item is a folder or not. | `optional[boolean]` | | `folder_name` | The name of the folder. Same as name. | `optional[text]` | ### Excel row reference ExcelRowRef represents a reference to a specific row within an Excel worksheet. This utility enables efficient access, manipulation, and reference of data within rows, providing essential information to uniquely identify and interact with a row's content. | Field Name | Description | Type | | ---------- | ---------------------------------- | -------- | | `id` | The unique identifier for the row. | `text` | | `index` | The index of the row. | `number` | ### Excel pivot table reference ExcelPivotTableRef represents a reference to a pivot table within an Excel worksheet.Graph API is read-only for pivot tables: list and refresh only. Cannot create, modify, or delete pivot tables via the API. | Field Name | Description | Type | | ---------- | ------------------------------------------------------------ | ------ | | `id` | The unique identifier for the pivot table. | `text` | | `name` | The name of the pivot table. | `text` | | `drive_id` | The unique identifier for the drive containing the workbook. | `text` | | `file_id` | The unique identifier for the workbook. | `text` | | `sheet_id` | The unique identifier for the worksheet. | `text` | ### Excel cell reference ExcelCellRef represents a reference to a specific cell within an Excel worksheet, serving as a utility to uniquely identify and manipulate data within the cell. It provides essential details to locate the cell precisely. | Field Name | Description | Type | | -------------- | ------------------------------------------------- | ---------------- | | `drive_id` | The unique identifier for the drive. | `text` | | `file_id` | The unique identifier for the file. | `text` | | `sheet_id` | The unique identifier for the sheet. | `text` | | `row_index` | The row of the cell. | `number` | | `column_index` | The column of the cell. | `number` | | `id` | The unique identifier for the cell. | `optional[text]` | | `row_id` | The unique identifier for the row of the cell. | `optional[text]` | | `column_id` | The unique identifier for the column of the cell. | `optional[text]` | | `address` | The address of the cell. | `optional[text]` | | `table_id` | The unique identifier for the table. | `optional[text]` | | Name | Type | | | ---------- | ---------------- | | | `id` | `optional[text]` | | | `drive_id` | `optional[text]` | | | Name | Type | | | ---------- | ---------------- | | | `id` | `optional[text]` | | | `drive_id` | `optional[text]` | | # Microsoft Office 365 Overview of the Microsoft Office 365 integration. {% hint style="info" %} The following documentation is for **Microsoft Office 365 v2.6.0**. {% endhint %} ## Overview Microsoft Office 365 provides comprehensive productivity suite with cloud-based collaboration and communication tools. This integration enables automated workflow management across Word, Excel, PowerPoint, and other Office applications. Enhance productivity and streamline business processes through integrated Microsoft ecosystem automation. ### Setup The following integrations need to be connected to your Kognitos workspace: * **Microsoft Office 365** #### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Permissions When using **client credentials** authentication, you need to have the following **application permissions** in Microsoft Graph: {% hint style="info" %} Application permissions are used when an app runs without a signed-in user *(such as with a client credentials flow)*. These permissions give the app organization-wide access and must be granted by an administrator in your Microsoft organization. For additional details, refer to Microsoft's [**guides**](https://learn.microsoft.com/en-us/graph/security-authorization#grant-permissions-to-an-application). {% endhint %} **User and Directory Access** * `User.Read.All` * `User.ReadWrite.All` * `Directory.Read.All` * `Directory.ReadWrite.All` **Mail Operations** * `Mail.Read` * `Mail.ReadWrite` * `Mail.ReadBasic` * `Mail.ReadBasic.All` * `Mail.ReadWrite.Shared` * `Mail.Send` **Calendar Operations** * `Calendars.ReadBasic` * `Calendars.Read` * `Calendars.ReadWrite` ### Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Client ID, Client Secret and Tenant ID Connect to the Microsoft Graph API using the provided client credentials. | Label | Description | Type | | ------------- | ------------------------------------------------------------ | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Client Secret | The client secret of the application registered in Azure AD. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | #### Connect using Client ID, Certificate and Tenant ID Connect to the Microsoft Graph API using certificate credentials. | Label | Description | Type | | ----------- | ------------------------------------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded X.509 certificate string containing both the certificate and private key. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | #### Connect using Client ID, Certificate, Private Key and Tenant ID Connect to the Microsoft Graph API using certificate and private key. | Label | Description | Type | | ----------- | -------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded certificate string. | `sensitive` | | Private Key | PEM-encoded private key string. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | ### Actions The following actions are available in the **Microsoft Office 365** integration: #### 1. Get a group's members from office365 Retrieves members of an Office 365 group accessible via the Microsoft Graph API. #### 2. Get some groups from office365 Get Office 365 groups accessible via the Microsoft Graph API. #### 3. Get some users from office365 Get Office 365 users accessible via the Microsoft Graph API. ### Concepts #### Office group An Office Group represents a group in the Microsoft Graph. It includes key user details such as display name,and email address. | Field Name | Description | Type | | --------------- | ----------------------------------------------------- | ---------------- | | `id` | The unique identifier for the group. | `text` | | `display_name` | The name displayed in the address book for the group. | `optional[text]` | | `email_address` | The group's email address. | `optional[text]` | #### Office user An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,email address, and job title. | Field Name | Description | Type | | --------------- | ------------------------------------------------------------- | ---------------- | | `id` | The unique identifier for the user. | `text` | | `display_name` | The name displayed in the address book for the user. | `optional[text]` | | `email_address` | The user's email address (usually their user principal name). | `optional[text]` | | `job_title` | The user's job title. | `optional[text]` | # Microsoft Outlook Overview of the Microsoft Outlook integration. {% hint style="info" %} The following documentation is for **Microsoft Outlook v2.6.0**. {% endhint %} ## Overview Microsoft Outlook provides enterprise email management with calendar, contacts, and task integration capabilities. This integration enables automated email processing, calendar management, and communication workflows. Streamline business communication and enhance productivity through automated email operations. ### Setup The following integrations need to be connected to your Kognitos workspace: * **Microsoft Outlook** * **Microsoft Office 365** {% hint style="info" %} Note: The **Microsoft Outlook** integration depends on **Microsoft Office 365** for core Microsoft capabilities. {% endhint %} #### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Permissions When using **client credentials** authentication, you need to have the following **application permissions** in Microsoft Graph: {% hint style="info" %} Application permissions are used when an app runs without a signed-in user *(such as with a client credentials flow)*. These permissions give the app organization-wide access and must be granted by an administrator in your Microsoft organization. For additional details, refer to Microsoft's [**guides**](https://learn.microsoft.com/en-us/graph/security-authorization#grant-permissions-to-an-application). {% endhint %} **User and Directory Access** * `User.Read.All` * `User.ReadWrite.All` * `Directory.Read.All` * `Directory.ReadWrite.All` **Mail Operations** * `Mail.Read` * `Mail.ReadWrite` * `Mail.ReadBasic` * `Mail.ReadBasic.All` * `Mail.ReadWrite.Shared` * `Mail.Send` **Calendar Operations** * `Calendars.ReadBasic` * `Calendars.Read` * `Calendars.ReadWrite` ### Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Client ID, Client Secret and Tenant ID Connect to the Microsoft Graph API using the provided client credentials. | Label | Description | Type | | ------------- | ------------------------------------------------------------ | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Client Secret | The client secret of the application registered in Azure AD. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | #### Connect using Client ID, Certificate and Tenant ID Connect to the Microsoft Graph API using certificate credentials. | Label | Description | Type | | ----------- | ------------------------------------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded X.509 certificate string containing both the certificate and private key. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | #### Connect using Client ID, Certificate, Private Key and Tenant ID Connect to the Microsoft Graph API using certificate and private key. | Label | Description | Type | | ----------- | -------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded certificate string. | `sensitive` | | Private Key | PEM-encoded private key string. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | ### Actions The following actions are available in the **Microsoft Outlook** integration: #### 1. Delete some emails Delete specific emails from an Outlook account. #### 2. Download an attachment Download an attachment from an event or email. #### 3. Forward an email to a recipient Forward an email to a specified recipient or group of recipients. #### 4. Get a group's events from outlook Get all the events from a group's calendar. #### 5. Get a user's event's attachments Get all the attachments from a user's event. #### 6. Get a user's events from outlook Get all the events from a user's calendar. #### 7. Get an email folder's subfolders Get all the subfolders from an email folder. #### 8. Get some email folder's emails Get emails from an Outlook folder based on specified filters. #### 9. Get the attachments from an email Get the attachments from an email. #### 10. Mark some emails Mark specified emails as read or unread. #### 11. Move an email to a target folder Move emails to a target folder. #### 12. Reply an email Reply to an email through Outlook with the specified details and attachments. #### 13. Retrieve some email folders from outlook Get all the email folders from the authenticated user's mailbox. #### 14. Retrieve some user's email folders Get all the email folders from a user's mailbox. #### 15. Send an email to a recipient Send an email through Outlook with the specified details and attachments. #### 16. Set an entity's event's body to a text Update the body of a calendar event. ### Concepts #### Outlook email An Outlook Email represents an email message in Microsoft Graph. | Field Name | Description | Type | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `id` | The unique identifier for the email. | `optional[text]` | | `folder_id` | The unique identifier for the folder containing the email. | `optional[text]` | | `subject` | The subject of the email. | `optional[text]` | | `body` | The body of the email. | `optional[text]` | | `recipients` | The recipients of the email. | `optional[list of text]` | | `state` | The state of the email (e.g., sent, received, draft, deleted, archived, unread). | `optional[text]` | | `sent_date_time` | The date and time the email was sent. | `optional[datetime]` | | `received_date_time` | The date and time the email was received. | `optional[datetime]` | | `sender` | The sender of the email. | `optional[text]` | | `cc_recipients` | The cc recipients of the email. | `optional[list of text]` | | `bcc_recipients` | The bcc recipients of the email. | `optional[list of text]` | | `user_id` | The id of the authenticated user making the requests. If it is None, the user is the using the "me" endpoints meaning delegated access. | `optional[text]` | | `has_attachments` | Whether the email has attachments or not. | `optional[boolean]` | | `conversation_id` | The ID of the conversation the email belongs to. | `optional[text]` | | `last_modified_date_time` | The date and time the email was last modified. | `optional[datetime]` | | `categories` | The categories associated with the email. | `optional[list of text]` | #### Outlook attachment An Outlook Attachment represents a file or item attached to a calendar event in Microsoft Graph. It includes the attachment name and content type. | Field Name | Description | Type | | --------------- | -------------------------------------------------------- | ---------------- | | `attachment_id` | The unique identifier for the attachment. | `optional[text]` | | `odata_type` | The OData type of the attachment. | `optional[text]` | | `user_id` | The user ID of the attachment. | `optional[text]` | | `name` | The name of the attachment. | `optional[text]` | | `event_id` | The ID of the event to which the attachment is attached. | `optional[text]` | | `email_id` | The ID of the email to which the attachment is attached. | `optional[text]` | #### Outlook email folder OutlookEmailFolder represents a folder within an Outlook mailbox, providing a way to organize and manage emails. It serves as a utility to group emails based on specific criteria, facilitating efficient email management and retrieval. | Field Name | Description | Type | | ---------- | ----------------------------------------------------- | ---------------- | | `id` | The unique identifier for the folder. | `optional[text]` | | `name` | The name of the folder. | `optional[text]` | | `user_id` | The id of the authenticated user making the requests. | `optional[text]` | #### Office user An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,email address, and job title. | Field Name | Description | Type | | --------------- | ------------------------------------------------------------- | ---------------- | | `id` | The unique identifier for the user. | `text` | | `display_name` | The name displayed in the address book for the user. | `optional[text]` | | `email_address` | The user's email address (usually their user principal name). | `optional[text]` | | `job_title` | The user's job title. | `optional[text]` | #### Outlook event An Outlook Calendar Event is a scheduled occurrence within an Outlook calendar that is managed through theMicrosoft Graph API. The event object includes essential details such as the subject, start and end times, attendees, and location, and supports advanced features like reminders, recurrence patterns, and time zone adjustments. | Field Name | Description | Type | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | | `id` | The unique identifier for the event. Read-only. | `text` | | `subject` | The text of the event's subject line. | `optional[text]` | | `body_preview` | The preview of the message associated with the event. It is in text format. | `optional[text]` | | `start` | The start date, time, and time zone of the event. By default, the start time is in UTC. | `optional[datetime]` | | `end` | The date, time, and time zone that the event ends. By default, the end time is in UTC. | `optional[datetime]` | | [`location`](#outlook-event-location) | The location of the event. | `optional[outlook event location]` | | [`locations`](#outlook-event-location) | The locations where the event is held or attended from. The location and locations properties always correspond with each other. If you update the location property, any prior locations in the locations collection would be removed and replaced by the new location value. | `optional[list of outlook event location]` | | [`organizer`](#outlook-email-address) | The organizer of the event. | `optional[outlook email address]` | | [`attendees`](#outlook-event-attendee) | The collection of attendees for the event. | `optional[list of outlook event attendee]` | #### Outlook event location An Outlook Event Location represents a specific location associated with a calendar event or meeting inMicrosoft Graph. It includes properties like the display name, address, coordinates, and location type, enabling precise identification and use of locations within calendar-related functionalities. | Field Name | Description | Type | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `display_name` | The name associated with the location. | `optional[text]` | | `email_address` | Optional email address of the location. | `optional[text]` | | `type` | The type of location. The possible values are: default, conferenceRoom, homeAddress, businessAddress,geoCoordinates, streetAddress, hotel, restaurant, localBusiness, postalAddress. Read-only. | `optional[text]` | | `uri` | Optional URI representing the location. | `optional[text]` | #### Outlook email address Represents an email address associated with a contact or calendar item inMicrosoft Graph. It includes only the name and email address fields. | Field Name | Description | Type | | ---------- | --------------------------------------------------- | ---------------- | | `name` | The display name associated with the email address. | `optional[text]` | | `address` | The email address. | `optional[text]` | #### Outlook event attendee An Outlook Event Attendee represents an attendee of a calendar event in Microsoft Graph. It includes the name, email address, attendee type, and response status fields. | Field Name | Description | Type | | --------------- | --------------------------------------------------------------------------------------------------------- | -------------------- | | `name` | The display name associated with the attendee. | `optional[text]` | | `email_address` | The email address of the attendee. | `optional[text]` | | `type` | The type of attendee as a string. Possible values are: required, optional, resource. | `optional[text]` | | `status` | The response status of the attendee as a string. Possible values are: accepted, declined, tentative, etc. | `optional[text]` | | `response_time` | The datetime when the response was recorded. | `optional[datetime]` | #### Office group An Office Group represents a group in the Microsoft Graph. It includes key user details such as display name,and email address. | Field Name | Description | Type | | --------------- | ----------------------------------------------------- | ---------------- | | `id` | The unique identifier for the group. | `text` | | `display_name` | The name displayed in the address book for the group. | `optional[text]` | | `email_address` | The group's email address. | `optional[text]` | # Microsoft SharePoint Overview of the Microsoft SharePoint integration. {% hint style="info" %} The following documentation is for **Microsoft SharePoint v2.6.0**. {% endhint %} ## Overview Microsoft SharePoint offers enterprise content management and collaboration platform for document sharing and team sites. This integration enables automated document workflows, content management, and team collaboration processes. Enhance organizational knowledge sharing and streamline document management. ### Setup The following integrations need to be connected to your Kognitos workspace: * **Microsoft SharePoint** * **Microsoft Office 365** {% hint style="info" %} Note: The **Microsoft SharePoint** integration depends on **Microsoft Office 365** for core Microsoft capabilities. {% endhint %} #### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} #### Credentials & Permissions To use the Microsoft SharePoint integration, you need to create an app registration in Microsoft Entra ID (formerly Azure AD) to obtain **credentials** and configure the appropriate **permissions**. {% stepper %} {% step %} **Sign in to the Azure Portal** Navigate to [**portal.azure.com**](https://azure.microsoft.com/en-us/get-started/azure-portal) with an account that has permissions to manage applications. From the main dashboard, select **Microsoft Entra ID** *(under **Azure Services**)*. {% endstep %} {% step %} **Create a New App Registration** 1. Click on + Add and select **App registration**. 2. Enter a **Name** for the app. For example: "Kognitos SharePoint Integration". 3. Under **Supported account types**, choose "Accounts in this organizational directory only". 4. Leave the **Redirect URI** field blank. 5. Click on Register to create the app. {% endstep %} {% step %} **Capture the Client ID and Tenant ID** After creating the app, you'll land on its **Overview** page. Copy the **Application (client) ID** and **Directory (tenant) ID** from this page.
{% endstep %} {% step %} **Generate a Client Secret** 1. Click on Manage on the left. 2. Select API Permissions from the dropdown menu. 3. Under **Client Secrets**, click on + New client secret. 4. Enter a description for the secret and choose an expiration period. 5. Click **Add**. Copy the Secret's **Value** as your **Client Secret**. {% hint style="warning" %} Client secret values cannot be viewed except immediately after creation. Be sure to save the secret when it is created before leaving the page! {% endhint %}
{% endstep %} {% step %} **Assign API Permissions** 1. In the app registration page, click on **Manage** in the left navigation. 2. Select **API Permissions** from the dropdown menu. 3. Click on **+ Add a permission**, then select **Microsoft Graph**. 4. Choose **Application permissions**, as the integration will access SharePoint without a signed-in user. 5. Choose **one** of the following permission options: 1. **Option A - Least Privileged** *(Recommended for security-sensitive environments)* 1. Search for and select the following permission: **Sites.Selected** 2. Click **Add permissions**. 3. Grant the application access to specific SharePoint sites: 1. Retrieve the SharePoint Site ID: 1. Log in to SharePoint and open the target site. 2. Append `/_api/site/id` to the site URL. 3. From the response, copy the value under **Edm.Guid** (this is the Site ID). 2. Using an account or application with elevated SharePoint permissions, run the following Microsoft Graph API request to authorize the app for that site: ``` POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions Content-Type: application/json { "roles": ["FullControl"], "grantedToIdentities": [{ "application": { "id": "", "displayName": "" } }] } ``` 3. Repeat this process for each SharePoint site the application needs to access. 2. **Option B - Broad Access: Permissions to All SharePoint Sites** 1. Search for and select the following permissions: 1. **Sites.Read.All** 2. **Sites.ReadWrite.All** 3. **Sites.Manage.All** 4. **Sites.FullControl.All** 2. Click **Add permissions**.
{% endstep %} {% step %} **Grant Admin Consent** On the **API permissions** screen, click on Grant admin consent for \[Your Organization Name] button, then select **Yes**. This authorizes the application to use the permissions you assigned across your organization.
{% endstep %} {% endstepper %} ### Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Client ID, Client Secret and Tenant ID Connect to the Microsoft Graph API using the provided client credentials. | Label | Description | Type | | ------------- | ------------------------------------------------------------ | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Client Secret | The client secret of the application registered in Azure AD. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | #### Connect using Client ID, Certificate and Tenant ID Connect to the Microsoft Graph API using certificate credentials. | Label | Description | Type | | ----------- | ------------------------------------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded X.509 certificate string containing both the certificate and private key. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | #### Connect using Client ID, Certificate, Private Key and Tenant ID Connect to the Microsoft Graph API using certificate and private key. | Label | Description | Type | | ----------- | -------------------------------------------------------- | ----------- | | Client ID | The client ID of the application registered in Azure AD. | `text` | | Certificate | PEM-encoded certificate string. | `sensitive` | | Private Key | PEM-encoded private key string. | `sensitive` | | Tenant ID | The tenant ID of the Azure AD directory. | `text` | ### Actions The following actions are available in the **Microsoft SharePoint** integration: #### 1. Add a column to a slist Adds a column to a given SharePoint list using the Microsoft Graph API. #### 2. Add an item to a slist Adds an item to a given SharePoint list using the Microsoft Graph API. #### 3. Copy an item to a folder Copies an item (folder or file) to a given folder using the Microsoft Graph API. #### 4. Create a folder in a document library Creates a new folder at the root of the given SharePoint document library using the Microsoft Graph API. #### 5. Create a folder in another folder Creates a new folder at the given SharePoint document library item using the Microsoft Graph API. #### 6. Create a list in a sharepoint site Creates a new list in a given SharePoint site using the Microsoft Graph API. #### 7. Delete a column from a list Deletes a column from a given SharePoint list using the Microsoft Graph API. #### 8. Delete a slist Deletes a list in a given SharePoint site using the Microsoft Graph API. #### 9. Delete an item Deletes an item (folder or file) within a given SharePoint document library using the Microsoft Graph API. #### 10. Delete an item from list Deletes one or many items in a given SharePoint list using the Microsoft Graph API. #### 11. Download a file Downloads a file from a given SharePoint document library using the Microsoft Graph API. #### 12. Edit an item Edits an item in a given SharePoint list using the Microsoft Graph API. #### 13. Get a folder's items Retrieves all child items from the specified document library folder using the Microsoft Graph API. #### 14. Get a folder at a path Retrieves the root folder of a given SharePoint document library using the Microsoft Graph API. #### 15. Get a root folder from a document library Retrieves the root folder of a given SharePoint document library using the Microsoft Graph API. #### 16. Get some items from a document library Retrieves all items within a given SharePoint document library using the Microsoft Graph API. #### 17. Get some site's document libraries Retrieves all document libraries within a given SharePoint site using the Microsoft Graph API. #### 18. Get some sites from sharepoint Get SharePoint sites accessible via the Microsoft Graph API. #### 19. Get some slist's items Retrieves all items within a given SharePoint list using the Microsoft Graph API. #### 20. Move an item to a folder Moves an item (folder or file) to a given folder using the Microsoft Graph API. #### 21. Rename a slist Renames a list in a given SharePoint site using the Microsoft Graph API. #### 22. Rename a column in a list Edits a column in a given SharePoint list using the Microsoft Graph API. #### 23. Rename an item to a name Renames a folder or a file using the Microsoft Graph API. #### 24. Retrieve a document library at a url Retrieves a SharePoint document library by its web URL using the Microsoft Graph API. #### 25. Retrieve a file at a url Retrieves a SharePoint file by its web URL using the Microsoft Graph API. #### 26. Retrieve a folder at a url Retrieves a SharePoint folder by its web URL using the Microsoft Graph API. #### 27. Retrieve a site at a url Retrieves a SharePoint site by its web URL using the Microsoft Graph API. #### 28. Retrieve a slist at a url Retrieves a SharePoint list by its web URL using the Microsoft Graph API. #### 29. Retrieve a slist as a table Retrieve a sharepoint list as a table. #### 30. Retrieve some column definitions from a slist Retrieves the column definitions of a given SharePoint list using the Microsoft Graph API. #### 31. Retrieve some site's lists Retrieves all lists within a given SharePoint site using the Microsoft Graph API. #### 32. Retrieve some site's subsites Retrieves all subsites within a given SharePoint site using the Microsoft Graph API. #### 33. Upload a file to a folder and get the file reference Uploads a file to a given SharePoint document library using the Microsoft Graph API. ### Concepts #### Sharepoint list A SharePoint list is a structured collection of data within a SharePoint site. It provides a way to organize and manage information in a tabular format, with columns representing different data fields and rows containing specific data entries.Lists are commonly used for tasks like tracking project progress, managing contacts, or storing custom data. | Field Name | Description | Type | | -------------------------- | ---------------------------------------- | ---------------- | | [`columns`](#list-of-text) | The columns of the list. | `list of text` | | `created_date_time` | The date and time the list was created. | `datetime` | | `display_name` | The display name of the list. | `text` | | `id` | The unique identifier for the list. | `text` | | `name` | The name of the list. | `text` | | `web_url` | The URL of the list. | `text` | | `site_id` | The id of the site this list belongs to. | `text` | | `description` | The description of the list. | `optional[text]` | #### Sharepoint list item A SharePoint list item represents an individual entry within a SharePoint list. It contains specific data values corresponding to the columns defined in the list. List items are used to store and manage structured data within a SharePoint list, enabling efficient organization and retrieval of information. | Field Name | Description | Type | | ---------- | ---------------------------------------- | ------ | | `id` | The unique identifier for the list item. | `text` | | `list_id` | The id of the list this item belongs to. | `text` | | `site_id` | The id of the site this item belongs to. | `text` | | `fields` | The fields of the list item. | `json` | | `web_url` | The URL of the list item. | `text` | #### Sharepoint file reference A Sharepoint File Reference is a reference to a file in a SharePoint document library. | Field Name | Description | Type | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | | `id` | The unique identifier for the document library. | `optional[text]` | | `name` | The name of the document library. | `optional[text]` | | `web_url` | URL that either displays the resource in the browser (for Office file formats), or is a direct link to the file (for other formats). | `optional[text]` | | [`parent_reference`](#parent_reference-sharepoint-file-reference) | Parent information, if the item has a parent. | `optional[json]` | | `is_folder` | Boolean flag indicating whenever this item is a folder or not. | `optional[boolean]` | | `file_name` | The name of the file. Same as name. | `optional[text]` | #### Sharepoint folder reference A Sharepoint Folder Reference is a reference to a folder in a SharePoint document library. | Field Name | Description | Type | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | | `id` | The unique identifier for the document library. | `optional[text]` | | `name` | The name of the document library. | `optional[text]` | | `web_url` | URL that either displays the resource in the browser (for Office file formats), or is a direct link to the file (for other formats). | `optional[text]` | | [`parent_reference`](#parent_reference-sharepoint-folder-reference) | Parent information, if the item has a parent. | `optional[json]` | | `is_folder` | Boolean flag indicating whenever this item is a folder or not. | `optional[boolean]` | | `folder_name` | The name of the folder. Same as name. | `optional[text]` | #### Sharepoint site A SharePoint site is a versatile web-based platform within Microsoft SharePoint designed for team collaboration,document management, and content sharing. It provides a centralized space where users can store and manage documents with version control, organize information in lists, create and publish web pages, and control permissions for different users. | Field Name | Description | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | | `id` | The unique identifier for the site. Read-only. | `text` | | `name` | The name of the site. Read-write. | `optional[text]` | | `display_name` | The full title for the site. Read-only. | `optional[text]` | | `web_url` | URL that either displays the resource in the browser (for Office file formats), or is a direct link to the file (for other formats). Read-only. | `optional[text]` | | `is_personal_site` | Identifies whether the site is personal or not. Read-only. | `optional[boolean]` | | `description` | Provides a user-visible description of the site. Optional. | `optional[text]` | #### Sharepoint document library A SharePoint Document Library is a specialized storage location within a SharePoint site designed for storing, organizing,and managing documents. It supports advanced document management features such as version control, metadata tagging, and workflow automation, making it ideal for team collaboration and enterprise content management. | Field Name | Description | Type | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | `id` | The unique identifier for the document library. Read-only. | `text` | | `drive_type` | Describes the type of drive represented by this resource. OneDrive personal drives will return personal. OneDrive for Business will return business. SharePoint document libraries will return documentLibrary. Read-only. | `optional[text]` | | `name` | The name of the document library. Read-write. | `optional[text]` | | `web_url` | URL that either displays the resource in the browser (for Office file formats), or is a direct link to the file (for other formats). Read-only. | `optional[text]` | | `description` | Provides a user-visible description of the document library. Optional. | `optional[text]` | #### Sharepoint list column A SharePoint list column definition represents the configuration and properties of a column within a SharePoint list. | Field Name | Description | Type | | -------------------------- | ------------------------------------------- | ---------------- | | `id` | The unique identifier for the column. | `text` | | `type` | The type of the column. | `text` | | `list_id` | The id of the list this column belongs to. | `text` | | `site_id` | The id of the site this column belongs to. | `text` | | `general_definition` | The general definition of the column. | `json` | | `type_specific_definition` | The type specific definition of the column. | `optional[json]` | **Concept attribute specifications** **parent\_reference (sharepoint file reference)** | Name | Type | | ---------- | ---------------- | | `id` | `optional[text]` | | `drive_id` | `optional[text]` | **parent\_reference (sharepoint folder reference)** | Name | Type | | ---------- | ---------------- | | `id` | `optional[text]` | | `drive_id` | `optional[text]` | # Microsoft Teams Overview of the Teams integration. {% hint style="info" %} The following documentation is for **Teams v2.6.0**. {% endhint %} ## Overview Enables interacting with and managing Microsoft Teams workspaces, channels, and communications via the Microsoft Graph API. Teams provides a collaborative platform for team communication, file sharing, and integrated applications. Ideal for businesses and developers seeking efficient team collaboration, virtual meetings, and workspace organization. This integration ensures secure and seamless access to these collaboration services. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Teams** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **Teams** integration: ### 1. Add a member to a channel Adds a member to a Teams channel. ### 2. Create a channel in a team Creates a new channel in a Microsoft Team. ### 3. Get some channels from a team Retrieves channels within a Microsoft Team. ### 4. Get some messages from a channel Retrieves messages from a Teams channel. ### 5. Get some teams from teams Retrieves Microsoft Teams accessible via the Microsoft Graph API. ### 6. Send a message to a channel Sends a message to a Teams channel. ### 7. Send a message to a user Sends a direct message to a user via Teams chat. ## Concepts ### Teams channel A Teams Channel represents a channel in Microsoft Teams. It includes key details such as display name,description, and membership type. | Field Name | Description | Type | | ----------------- | ------------------------------------------------------------------- | -------------------------------------------- | | `display_name` | The name displayed for the channel. | `text` | | `description` | The description of the channel. | `optional[text]` | | `membership_type` | The type of membership for the channel (standard, private, shared). | `optional[enum[private, shared, standard]?]` | | `team_id` | The ID of the team that contains this channel. | `optional[text]` | | `id` | The unique identifier for the channel (optional for creation). | `optional[text]` | | `web_url` | The web URL for the channel. | `optional[text]` | ### Office user An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,email address, and job title. | Field Name | Description | Type | | --------------- | ------------------------------------------------------------- | ---------------- | | `id` | The unique identifier for the user. | `text` | | `display_name` | The name displayed in the address book for the user. | `optional[text]` | | `email_address` | The user's email address (usually their user principal name). | `optional[text]` | | `job_title` | The user's job title. | `optional[text]` | ### Teams team A Teams Team represents a team in Microsoft Teams. It includes key details such as display name,description, and visibility settings. | Field Name | Description | Type | | -------------- | --------------------------------------------- | ---------------- | | `id` | The unique identifier for the team. | `text` | | `display_name` | The name displayed for the team. | `optional[text]` | | `description` | The description of the team. | `optional[text]` | | `visibility` | The visibility of the team (private, public). | `optional[text]` | | `web_url` | The web URL for the team. | `optional[text]` | ### Teams message A Teams Message represents a message in a Microsoft Teams channel or chat. It includes key details such as content,sender, and creation time. | Field Name | Description | Type | | ------------------------ | ------------------------------------------------------------------------ | ---------------- | | `id` | The unique identifier for the message. | `text` | | `content` | The content of the message. | `optional[text]` | | `created_datetime` | The datetime when the message was created. | `optional[text]` | | `last_modified_datetime` | The datetime when the message was last modified. | `optional[text]` | | `from_user` | The user who sent the message. | `optional[text]` | | `channel_id` | The ID of the channel where the message was sent (for channel messages). | `optional[text]` | | `team_id` | The ID of the team that contains the channel (for channel messages). | `optional[text]` | | `chat_id` | The ID of the chat where the message was sent (for chat messages). | `optional[text]` | | `web_url` | The web URL for the message. | `optional[text]` | # MSG Overview of the MSG integration. {% hint style="info" %} The following documentation is for **MSG v1.8.0**. {% endhint %} ## Overview Enables reading MSG files. ## Setup The following integrations need to be connected to your Kognitos workspace: * **MSG** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **MSG** integration: ### 1. Check msg has attachments Check if a MSG file has attachments. ### 2. Check msg is forward Check if a MSG file is a forwarded email. ### 3. Check msg is reply Check if a MSG file is a reply to another email. ### 4. Convert msg to eml Convert a MSG file to EML format. ### 5. Get msg attachments Get the attachments from a MSG file as IO objects. ### 6. Get msg bcc recipients Get the BCC recipients from a MSG file. ### 7. Get msg body Get the body from a MSG file. ### 8. Get msg cc recipients Get the CC recipients from a MSG file. ### 9. Get msg date Get the date from a MSG file. ### 10. Get msg message identifier Get the Message-ID from a MSG file. ### 11. Get msg parent message identifier Get the In-Reply-To header from a MSG file. ### 12. Get msg reply address Get the Reply-To address from a MSG file. ### 13. Get msg sender Get the sender from a MSG file. ### 14. Get msg subject Get the subject from a MSG file. ### 15. Get msg to recipients Get the To recipients from a MSG file. # MSSQL Overview of the MSSQL integration. {% hint style="info" %} The following documentation is for **MSSQL v2.1.0**. {% endhint %} ## Overview Enables connecting to and querying Microsoft SQL Server databases. {% hint style="success" %} The MSSQL integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **MSSQL** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your MSSQL connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Host, Port, Username, Password and Database Name Connect to a Microsoft SQL Server database using the provided connection parameters. | Label | Description | Type | | ------------- | ------------- | ----------- | | Host | Host | `text` | | Port | Port | `text` | | Username | Username | `text` | | Password | Password | `sensitive` | | Database Name | Database Name | `text` | # NetSuite Overview of the Netsuite integration. {% hint style="info" %} The following documentation is for **Netsuite v2.1.8**. {% endhint %} ## Overview The Netsuite BDK integration connects to Oracle NetSuite ERP systems and automatically discovers all your business entities. From customers and employees to transactions and custom records, the Netsuite integration allows you to seamlessly read, create, and update any business entities in your NetSuite instance. {% hint style="success" %} The Netsuite integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Netsuite** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your Netsuite connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Consumer key, Consumer secret, Token ID, Token secret and Account ID Connects to Netsuite using token based authentication (TBA). | Label | Description | Type | | --------------- | -------------------------------------------- | ----------- | | Consumer key | The consumer key for the Netsuite account | `sensitive` | | Consumer secret | The consumer secret for the Netsuite account | `sensitive` | | Token ID | The token ID for the Netsuite account | `sensitive` | | Token secret | The token secret for the Netsuite account | `sensitive` | | Account ID | The account ID for the Netsuite account | `text` | ## Actions The following actions are available in the **Netsuite** integration: ### 1. Retrieve a file's information from netsuite Get a file's information from NetSuite's File Cabinet, using the SOAP API. ### 2. Retrieve a schema from netsuite Get the JSON schema for an entity ### 3. Retrieve an attachment from netsuite Get an attachment from NetSuite's File Cabinet, using the SOAP API. {% hint style="info" %} In addition to these built-in actions, the Netsuite integration supports **custom actions** that are discovered from your specific system. The actions available depend on which services you enable through the [discovery process](#discovering-actions). {% endhint %} # OpenAI Overview of the OpenAI integration. {% hint style="info" %} The following documentation is for **OpenAI v1.1.4**. {% endhint %} ## Overview This integration connects to OpenAI's GPT models, enabling you to leverage advanced AI capabilities for text generation, analysis, and intelligent automation workflows. ### Setup The following integrations need to be connected to your Kognitos workspace: * **OpenAI** #### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} #### Credentials **1. OpenAI API Key** Follow these steps to obtain your OpenAI API key: {% stepper %} {% step %} **Log In to OpenAI** Navigate to the [**OpenAI Platform**](https://auth.openai.com/log-in) and log in with your credentials. {% endstep %} {% step %} **API Keys** Open **Account Settings**, then navigate to [**API Keys**](https://platform.openai.com/account/api-keys)**.** {% endstep %} {% step %} **Generate a New API Key** Click **Create new secret key**. Copy the key immediately — it will only be shown once. {% endstep %} {% endstepper %} ### Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using API Key Connect using an API key. | Label | Description | Type | | ------- | ------------------------------- | ----------- | | API Key | The API key for authentication. | `sensitive` | ### Actions The following actions are available in the **OpenAI** integration: #### 1. Prompt openai Send a prompt to the OpenAI LLM and get a response. # OpenSearch Overview of the OpenSearch integration. {% hint style="info" %} The following documentation is for **OpenSearch v2.0.1**. {% endhint %} ## Overview OpenSearch is a distributed, open-source search and analytics suite used for a broad set of use cases like real-time application monitoring, log analytics, and website search. This integration enables automated index management, document indexing, search operations, and data analytics workflows. Leverage powerful search capabilities and streamline data discovery processes. ## Setup The following integrations need to be connected to your Kognitos workspace: * **OpenSearch** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Hosts, Username and Password Connect via http credentials | Label | Description | Type | | -------- | -------------------------- | ----------- | | Hosts | comma-separated hosts | `text` | | Username | the username for http auth | `text` | | Password | The password for http auth | `sensitive` | ## Actions The following actions are available in the **OpenSearch** integration: ### 1. Create a document in opensearch Create a document in opensearch ### 2. Delete a document from opensearch Delete a document from opensearch ### 3. Get a document from opensearch Get a document from opensearch by its ID ### 4. Query some documents from opensearch Query documents from Opensearch ### 5. Update a document in opensearch Update a document in opensearch ## Concepts ### Opensearch document Represents an Document in Opensearch. | Field Name | Description | Type | | ------------ | ---------------------------------------------- | ------ | | `id` | The ID of the document. | `text` | | `index_name` | The name of the index the document belongs to. | `text` | | `source` | The document values. | `json` | # Open Weather Overview of the Open Weather integration. {% hint style="info" %} The following documentation is for **Open Weather v1.6.2**. {% endhint %} ## Overview OpenWeather provides comprehensive weather data and forecasting services through robust APIs. This integration enables real-time weather information retrieval, forecast data access, and weather-based automation triggers. Incorporate weather intelligence into your decision-making and operational workflows. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Open Weather** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using API Key Authenticate to Open Weather API using the specified API key. | Label | Description | Type | | ------- | ------------------------------------- | ----------- | | API Key | The API key to be used for connecting | `sensitive` | ## Actions The following actions are available in the **Open Weather** integration: ### 1. Get the current temperature at a city Get the current temperature for a specified city. # Oracle Fusion Overview of the Oracle Fusion integration. {% hint style="info" %} The following documentation is for **Oracle Fusion v1.0.5**. {% endhint %} ## Overview Access and organize enterprise data in Oracle Fusion. Oracle Fusion provides a centralized way to access and organize Oracle Fusion data such as financials, supply chain, and human capital information. It can be used to create, retrieve, update and delete Oracle Fusion resources, as well as perform certain supported actions on them. {% hint style="success" %} The Oracle Fusion integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Oracle Fusion** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your Oracle Fusion connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Instance URL, Username and Password Connects to Oracle Fusion using the username and password. | Label | Description | Type | | ------------ | ---------------------------------- | ----------- | | Instance URL | The URL for the Oracle instance | `text` | | Username | The username of the Oracle account | `text` | | Password | The password of the Oracle account | `sensitive` | # PDF Overview of the PDF integration. {% hint style="info" %} The following documentation is for **PDF v1.8.0**. {% endhint %} ## Overview Enables converting PDF files to other formats. ## Setup The following integrations need to be connected to your Kognitos workspace: * **PDF** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **PDF** integration: ### 1. Convert a pdf file to docx Convert a PDF file to DOCX format. ### 2. Extract pages from a pdf Extracts specific pages from a PDF file to create a new PDF. ### 3. Get a pdf's fields Gets all form fields from a PDF file. ### 4. Get a pdf's labels Gets all text labels (text spans) from a PDF file. ### 5. Get a pdf's lines Gets all text lines from a PDF file. ### 6. Get a pdf's page count Gets the total number of pages in a PDF file. ### 7. Read a pdf file Read text from a PDF file, optionally by page. ### 8. Remove duplicates from a pdf Removes duplicate pages from a PDF based on text similarity. ### 9. Set a pdf field's value Sets the value of a form field in a PDF. ## Concepts ### Pdf Configuration for PDF to DOCX conversion.All fields have optimal defaults. Override specific values as needed. | Field Name | Description | Type | | -------------------------------- | --------------------------------------------------- | ------------------- | | `debug` | Set to True for debugging layout issues | `optional[boolean]` | | `ignore_page_error` | Continue conversion even if a page fails | `optional[boolean]` | | `parse_lattice_table` | Parse tables with visible borders | `optional[boolean]` | | `parse_stream_table` | Parse tables without visible borders | `optional[boolean]` | | `extract_stream_table` | Extract stream tables separately | `optional[boolean]` | | `clip_image_res_ratio` | Resolution ratio (4x = 288dpi from 72dpi base) | `optional[number]` | | `min_section_height` | Minimum height for a valid section | `optional[number]` | | `max_line_spacing_ratio` | Maximum line spacing ratio | `optional[number]` | | `line_overlap_threshold` | Delete overlapping lines (higher = less aggressive) | `optional[number]` | | `line_break_width_ratio` | Break line if too narrow | `optional[number]` | | `line_break_free_space_ratio` | Break line if too much free space | `optional[number]` | | `line_separate_threshold` | Distance threshold for separate lines | `optional[number]` | | `new_paragraph_free_space_ratio` | New paragraph threshold | `optional[number]` | | `lines_left_aligned_threshold` | Left alignment threshold (points) | `optional[number]` | | `lines_right_aligned_threshold` | Right alignment threshold (points) | `optional[number]` | | `lines_center_aligned_threshold` | Center alignment threshold (points) | `optional[number]` | | `connected_border_tolerance` | Border connection tolerance | `optional[number]` | | `max_border_width` | Maximum border width | `optional[number]` | | `min_border_clearance` | Minimum clearance between borders | `optional[number]` | | `page_margin_factor_top` | Top margin reduction factor \[0,1] | `optional[number]` | | `page_margin_factor_bottom` | Bottom margin reduction factor \[0,1] | `optional[number]` | | `shape_min_dimension` | Ignore shapes smaller than this | `optional[number]` | | `float_image_ignorable_gap` | Float image gap threshold | `optional[number]` | | `min_svg_gap_dx` | Merge vector graphics horizontal gap | `optional[number]` | | `min_svg_gap_dy` | Merge vector graphics vertical gap | `optional[number]` | | `min_svg_w` | Minimum SVG width | `optional[number]` | | `min_svg_h` | Minimum SVG height | `optional[number]` | | `delete_end_line_hyphen` | Keep hyphens at line ends | `optional[boolean]` | | `multi_processing` | Enable for faster conversion of large files | `optional[boolean]` | | `cpu_count` | 0 = use all CPUs, or specify number | `optional[number]` | ### Pdf field Represents a form field extracted from a PDF. | Field Name | Description | Type | | ---------- | ----------------------------------------------- | ---------------- | | `name` | The field name | `text` | | `value` | The current field value | `optional[text]` | | `type` | The field type (text, checkbox, combobox, etc.) | `text` | | `page` | Page number (0-indexed) | `number` | | `bbox` | Bounding box coordinates | `json` | ### Pdf bounding box Represents the bounding box coordinates for a PDF element. | Field Name | Description | Type | | ---------- | ------------------- | -------- | | `x0` | Left x-coordinate | `number` | | `y0` | Top y-coordinate | `number` | | `x1` | Right x-coordinate | `number` | | `y1` | Bottom y-coordinate | `number` | ### Pdf label Represents a text label (text span) extracted from a PDF. | Field Name | Description | Type | | ---------- | ------------------------ | -------- | | `text` | The label text content | `text` | | `page` | Page number (0-indexed) | `number` | | `bbox` | Bounding box coordinates | `json` | ### Pdf line Represents a text line extracted from a PDF. | Field Name | Description | Type | | ---------- | ------------------------ | -------- | | `text` | The complete line text | `text` | | `page` | Page number (0-indexed) | `number` | | `bbox` | Bounding box coordinates | `json` | # Postgres Overview of the Postgres integration. {% hint style="info" %} The following documentation is for **Postgres v2.1.0**. {% endhint %} ## Overview Enables connecting to, querying, and managing PostgreSQL databases. {% hint style="success" %} The Postgres integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Postgres** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your Postgres connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Host, Port, Username, Password and Database Name Connect to a PostgreSQL database using the provided connection parameters. | Label | Description | Type | | ------------- | ------------- | ----------- | | Host | Host | `text` | | Port | Port | `text` | | Username | Username | `text` | | Password | Password | `sensitive` | | Database Name | Database Name | `text` | # QuickBooks Overview of the Quickbooks integration. {% hint style="info" %} The following documentation is for **Quickbooks v2.6.0**. {% endhint %} ## Overview Automate accounting workflows by managing bills and records in QuickBooks. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Quickbooks** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using token Connects to QuickBooks using OAuth access token. | Label | Description | Type | | ----- | ----------------------------------------------------- | ------ | | token | The OAuth access token for QuickBooks authentication. | `text` | ## Actions The following actions are available in the **Quickbooks** integration: ### 1. Attach a file to the bill and get the attachment Upload an attachment to an existing bill in QuickBooks. ### 2. Create a bill Create a new bill in QuickBooks from the provided bill details. ### 3. Create a bill from a purchase order Create a new bill in QuickBooks based on an existing purchase order. ### 4. Create an invoice Create a new invoice in QuickBooks from the provided invoice details. ### 5. Delete an invoice Delete/void an invoice in QuickBooks. ### 6. Delete an invoice by id Delete/void an invoice in QuickBooks by invoice ID. ### 7. Edit a bill Edit an existing bill in QuickBooks by updating it with new information. ### 8. Edit an invoice Edit an existing invoice in QuickBooks by updating it with new information. ### 9. Retrieve bills Retrieve bills in QuickBooks from the company. ### 10. Retrieve customers Retrieve customers in QuickBooks from the company. ### 11. Retrieve invoices Retrieve invoices in QuickBooks from the company. ### 12. Retrieve items Retrieve items in QuickBooks from the company. ### 13. Retrieve purchase orders Retrieve purchase orders in QuickBooks from the company. ### 14. Retrieve vendors Retrieve vendors in QuickBooks from the company. ### 15. Retrieve a report Retrieve a specific report from QuickBooks. ### 16. Update an item Update an existing item in QuickBooks. ## Concepts ### Quickbooks bill input Input data for creating a QuickBooks Bill with mixed line item types. | Field Name | Description | Type | | ----------------------- | -------------------------------------------------------- | --------------------- | | `vendor` | The vendor in QuickBooks. | `json` | | [`items`](#list-of-any) | List of line items (can be item-based or account-based). | `list of list of any` | | `terms` | Optional sales terms name. | `optional[text]` | | `bill_date` | The bill date in YYYY-MM-DD format. | `optional[text]` | | `due_date` | The due date in YYYY-MM-DD format. | `optional[text]` | | `bill_no` | Optional bill number. | `optional[text]` | ### Quickbooks vendor A comprehensive representation of a QuickBooks Vendor. | Field Name | Description | Type | | ---------------------------------------- | -------------------------------------------- | ------------------------------ | | `id` | The unique identifier for the vendor. | `text` | | `display_name` | The display name of the vendor. | `text` | | `company_name` | The company name of the vendor. | `optional[text]` | | `first_name` | The first name of the vendor contact person. | `optional[text]` | | `last_name` | The last name of the vendor contact person. | `optional[text]` | | `print_on_check_name` | The name to print on checks. | `optional[text]` | | `email` | The primary email address of the vendor. | `optional[text]` | | `phone` | The primary phone number of the vendor. | `optional[text]` | | `website` | The vendor's website URL. | `optional[text]` | | [`billing_address`](#quickbooks-address) | The billing address of the vendor. | `optional[quickbooks address]` | | `account_number` | The vendor's account number. | `optional[text]` | | `balance` | The current balance owed to the vendor. | `optional[number]` | | `default_terms` | The default payment terms for the vendor. | `optional[text]` | | `is_1099_contractor` | Whether the vendor is a 1099 contractor. | `optional[boolean]` | | `is_active` | Whether the vendor is currently active. | `optional[boolean]` | ### Quickbooks bill A created QuickBooks Bill. | Field Name | Description | Type | | ------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- | | `id` | The unique identifier of the bill in QuickBooks. | `text` | | `doc_number` | The document number of the bill. | `text` | | `vendor_name` | The name of the vendor. | `text` | | `total_amount` | The total amount of the bill. | `number` | | `balance` | The current balance of the bill from QuickBooks. | `number` | | `bill_date` | The bill date. | `optional[text]` | | `due_date` | The due date. | `optional[text]` | | [`terms`](#terms-quickbooks-bill) | The payment terms reference with id and name. | `optional[json]` | | [`location`](#location-quickbooks-bill) | The department/location reference with id and name. | `optional[json]` | | `items` | List of bill line items. | `optional[list of list of quickbooks item` or `quickbooks account based line?]` | | [`custom_fields`](#quickbooks-custom-field) | List of custom fields associated with the bill. | `optional[list of quickbooks custom field]` | | [`attachment_ref`](#quickbooks-attachment) | The attachment reference if an attachment was uploaded. | `optional[quickbooks attachment]` | | `created_time` | When the bill was created. | `optional[text]` | | `last_updated` | When the bill was last updated | `optional[text]` | ### Quickbooks custom field Represents a custom field in QuickBooks. | Field Name | Description | Type | | --------------- | ------------------------------------------------------ | ---------------- | | `definition_id` | The unique identifier for the custom field definition. | `text` | | `name` | The name of the custom field. | `text` | | `field_type` | The type of the custom field (e.g., 'StringType'). | `text` | | `string_value` | The string value of the custom field. | `optional[text]` | ### Quickbooks attachment An attachment to a QuickBooks bill. | Field Name | Description | Type | | -------------- | ------------------------------------------------------ | ------------------ | | `id` | The unique identifier of the attachment in QuickBooks. | `text` | | `file_name` | The name of the attached file. | `text` | | `note` | Optional note associated with the attachment. | `optional[text]` | | `content_type` | The MIME type of the attachment. | `optional[text]` | | `size` | The size of the attachment in bytes. | `optional[number]` | ### Quickbooks purchase order A created QuickBooks Purchase Order. | Field Name | Description | Type | | ------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------- | | `id` | The unique identifier of the purchase order in QuickBooks. | `text` | | `doc_number` | The document number of the purchase order. | `text` | | `vendor_name` | The name of the vendor. | `text` | | `total_amount` | The total amount of the purchase order. | `number` | | `po_status` | The status of the purchase order (e.g., "Open", "Closed"). | `optional[text]` | | `po_date` | The purchase order date. | `optional[text]` | | `due_date` | The due date. | `optional[text]` | | `memo` | Memo or notes for the purchase order. | `optional[text]` | | `private_note` | Private note for the purchase order. | `optional[text]` | | [`terms`](#terms-quickbooks-purchase-order) | The payment terms reference. | `optional[json]` | | [`location`](#location-quickbooks-purchase-order) | The department/location. | `optional[json]` | | `ship_method` | The shipping method. | `optional[text]` | | `vendor_address` | The vendor address for the purchase order. | `optional[text]` | | `ship_address` | The shipping address. | `optional[text]` | | `exchange_rate` | The exchange rate used. | `optional[number]` | | `global_tax_calculation` | The tax calculation method. | `optional[text]` | | `items` | List of purchase order line items. | `optional[list of list of any?]` | | [`custom_fields`](#quickbooks-custom-field) | List of custom fields associated with the purchase order. | `optional[list of quickbooks custom field]` | | `created_time` | When the purchase order was created. | `optional[text]` | | `last_updated` | When the purchase order was last updated. | `optional[text]` | ### Quickbooks invoice input Input data for creating a QuickBooks Invoice with mixed line item types. | Field Name | Description | Type | | ------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------- | | `customer` | The customer in QuickBooks. | `json` | | [`items`](#list-of-any) | List of line items (can be sales-item or description-only). | `list of list of any` | | [`custom_fields`](#quickbooks-custom-field) | Optional list of custom fields for the invoice. | `optional[list of quickbooks custom field]` | | `terms` | Optional sales terms name. | `optional[text]` | | `invoice_date` | The invoice date in YYYY-MM-DD format. | `optional[text]` | | `due_date` | The due date in YYYY-MM-DD format. | `optional[text]` | | `invoice_no` | Optional invoice number. | `optional[text]` | ### Quickbooks customer A comprehensive representation of a QuickBooks Customer. | Field Name | Description | Type | | ----------------------------------------- | ---------------------------------------------- | ------------------------------ | | `id` | The unique identifier for the customer. | `text` | | `display_name` | The display name of the customer. | `text` | | `company_name` | The company name of the customer. | `optional[text]` | | `first_name` | The first name of the customer contact person. | `optional[text]` | | `last_name` | The last name of the customer contact person. | `optional[text]` | | `print_on_check_name` | The name to print on checks. | `optional[text]` | | `email` | The primary email address of the customer. | `optional[text]` | | `phone` | The primary phone number of the customer. | `optional[text]` | | `website` | The customer's website URL. | `optional[text]` | | [`billing_address`](#quickbooks-address) | The billing address of the customer. | `optional[quickbooks address]` | | [`shipping_address`](#quickbooks-address) | The shipping address of the customer. | `optional[quickbooks address]` | | `account_number` | The customer's account number. | `optional[text]` | | `balance` | The current balance owed by the customer. | `optional[number]` | | `default_terms` | The default payment terms for the customer. | `optional[text]` | | `is_active` | Whether the customer is currently active. | `optional[boolean]` | ### Quickbooks invoice A created QuickBooks Invoice. | Field Name | Description | Type | | ------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `id` | The unique identifier of the invoice in QuickBooks. | `text` | | `doc_number` | The document number of the invoice. | `text` | | `customer_name` | The name of the customer. | `text` | | `total_amount` | The total amount of the invoice. | `number` | | `balance` | The current balance of the invoice from QuickBooks. | `number` | | `invoice_date` | The invoice date. | `optional[text]` | | `due_date` | The due date. | `optional[text]` | | `terms` | The sales terms name. | `optional[text]` | | `items` | List of invoice line items. | `optional[list of list of quickbooks sales item line` or `quickbooks description only line?]` | | [`custom_fields`](#quickbooks-custom-field) | List of custom fields associated with the invoice. | `optional[list of quickbooks custom field]` | | `created_time` | When the invoice was created. | `optional[text]` | | `last_updated` | When the invoice was last updated | `optional[text]` | ### Quickbooks item A QuickBooks item (product, service, or category). | Field Name | Description | Type | | ------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------- | | `id` | The unique identifier for the item | `text` | | `name` | The name of the item | `text` | | `type` | The type of item (Service, Inventory, NonInventory, Category, etc.) | `text` | | `sku` | The SKU code for the item | `optional[text]` | | `description` | Description of the item | `optional[text]` | | `unit_price` | The unit price for sales | `optional[number]` | | `purchase_cost` | The cost to purchase the item | `optional[number]` | | `qty_on_hand` | Quantity on hand (for inventory items) | `optional[number]` | | [`income_account_ref`](#income_account_ref-quickbooks-item) | Reference to the income account | `optional[json]` | | [`expense_account_ref`](#expense_account_ref-quickbooks-item) | Reference to the expense account | `optional[json]` | | [`asset_account_ref`](#asset_account_ref-quickbooks-item) | Reference to the asset account | `optional[json]` | | [`parent_ref`](#parent_ref-quickbooks-item) | Reference to the parent category (for sub-categories) | `optional[json]` | | `is_active` | Whether the item is active | `optional[boolean]` | | `sync_token` | The sync token for updates | `optional[text]` | | `created_time` | The timestamp when the item was created | `optional[text]` | | `last_updated` | The timestamp when the item was last updated | `optional[text]` | | `taxable` | Whether the item is taxable | `optional[boolean]` | | `fully_qualified_name` | The fully qualified name of the item | `optional[text]` | | `purchase_desc` | Purchase description of the item | `optional[text]` | | `track_qty_on_hand` | Whether to track quantity on hand | `optional[boolean]` | | `inv_start_date` | The inventory start date (for inventory items) | `optional[text]` | | `domain` | The domain of the item | `optional[text]` | | `sparse` | Whether the item is sparse | `optional[boolean]` | ### Quickbooks report A QuickBooks report with its header, columns, and grouped table sections.This concept represents quickbooks reports, where data is organized into logical groupings. | Field Name | Description | Type | | --------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `report_type` | The type of report that was generated | `enum[account_list_detail, ap_detail, ap_summary, ar_detail, ar_summary, transaction_list]` | | `header` | Header information containing report metadata | `json` | | [`columns`](#columns-quickbooks-report) | Column definitions for the report | `list of json` | | [`tables`](#tables-quickbooks-report) | List of table sections, each representing a grouped data section | `list of json` | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ------ | ---------------- | | | `id` | `optional[text]` | | | `name` | `optional[text]` | | | Name | Type | | | ----------- | ---------------- | | | `col_type` | `text` | | | `col_title` | `text` | | | `metadata` | `optional[json]` | | | Name | Type | | | ---------- | ---------------- | | | `header` | `text` | | | `data` | `table` | | | `type` | `text` | | | `group` | `optional[text]` | | | `raw_data` | `optional[json]` | | # Raindrop Overview of the Raindrop integration. {% hint style="info" %} The following documentation is for **Raindrop v1.1.0**. {% endhint %} ## Overview Enables managing saved links, collections, and tags on Raindrop.io. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Raindrop** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using Test Token Connect to Raindrop.io using a test token. | Label | Description | Type | | ---------- | ---------------------------------------------------------------------------------------------------------------- | ----------- | | Test Token | The test token from your Raindrop.io application settings. It looks like "ae261404-11r4-47c0-bce3-e18a423da828". | `sensitive` | #### OAuth Authorization Code Connect to Raindrop using OAuth. Provide the following from your OAuth application: | Label | Description | Type | | ------------- | ----------------------- | ----------- | | Client ID | OAuth client identifier | `text` | | Client Secret | OAuth client secret | `sensitive` | ## Actions {% hint style="info" %} The available actions for **Raindrop** are listed in the product UI on the integration page once you create a connection. {% endhint %} # S3 Overview of the S3 integration. {% hint style="info" %} The following documentation is for **S3 v1.6.4**. {% endhint %} ## Overview Manages files and folders in AWS S3. ## Setup The following integrations need to be connected to your Kognitos workspace: * **S3** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID Assumes a role using the provided AWS credentials. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID for the initial authentication. | `text` | | AWS Secret Access Key | The AWS Secret Access Key for the initial authentication. | `sensitive` | | AWS Region | The AWS Region for the initial authentication. | `text` | | AWS Role ARN | The ARN of the role to assume. | `text` | | AWS External ID | An optional external ID that might be required by the role's trust policy. | `sensitive` | ### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region Connects to an API using the provided API key. | Label | Description | Type | | --------------------- | ------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID | `text` | | AWS Secret Access Key | The AWS Secret Access Key | `sensitive` | | AWS Region | The AWS Region | `text` | ## Actions The following actions are available in the **S3** integration: ### 1. Copy an item to a folder Create a copy of an item in a folder. ### 2. Create a folder in another folder Create a folder in another folder. ### 3. Delete an item Delete an item. ### 4. Download a file Get a file as a file object. ### 5. Get buckets from s3 Get buckets from AWS S3. ### 6. Get a file at a path Get a reference to a file at a path. ### 7. Get a folder at a path Get a reference to a folder at a path. ### 8. Get a root folder from a bucket Get a reference to the root folder in a bucket. ### 9. Get some folder's items Get items from a folder. ### 10. Move an item to a folder Update an item's location to a folder. ### 11. Rename an item to a name Update an item's name. ### 12. Upload a file to a folder Create a file in a folder. ## Concepts ### S3 file reference Represents a reference to a file in an S3 bucket. | Field Name | Description | Type | | ------------- | ----------------------------------------------------------------------------------- | -------- | | `bucket_name` | The name of the S3 bucket containing the file. | `text` | | `file_path` | The full path of the file within the bucket, including the file name and extension. | `text` | | `parent_path` | The path of the parent folder of the file. | `text` | | `name` | The name of the file. | `text` | | `e_tag` | The ETag of the file. | `text` | | `s3_uri` | The S3 URI of the file. | `text` | | `size` | The size of the file in bytes. | `number` | ### S3 folder reference Represents a reference to a folder in an S3 bucket. | Field Name | Description | Type | | ------------- | ----------------------------------------------------------------------------------------------------------- | -------- | | `bucket_name` | The name of the S3 bucket containing the folder. | `text` | | `folder_path` | The path of the folder within the bucket. Should end with a trailing slash ('/') to indicate it's a folder. | `text` | | `parent_path` | The path of the parent folder of the folder. | `text` | | `name` | The name of the folder. | `text` | | `e_tag` | The ETag of the folder. | `text` | | `s3_uri` | The S3 URI of the folder. | `text` | | `size` | The size of the folder in bytes. | `number` | ### S3 bucket Represents a S3 bucket. | Field Name | Description | Type | | ---------- | --------------------- | ------ | | `name` | Name of the S3 Bucket | `text` | # Salesforce Overview of the Salesforce integration. {% hint style="info" %} The following documentation is for **Salesforce v2.0.4**. {% endhint %} ## Overview Salesforce is a CRM platform for managing sales, customer relationships, and business operations. This integration lets you create, update, and delete Salesforce objects, manage reports, and send emails directly from your Kognitos automations. {% hint style="success" %} The Salesforce integration supports **discovery**. Once connected, Kognitos automatically learns the object types in your Salesforce instance, including custom objects. You can then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Salesforce** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the Salesforce objects and operations available in your instance: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your Salesforce connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable objects** Browse or search for the Salesforce objects you need (e.g., "Account", "Opportunity", "Custom\_Object\_\_c"). Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Credentials This section explains how to obtain the credentials needed to connect Salesforce. You can choose from different authentication methods, each requiring different credentials. ### 1. Client Credentials This connection method uses OAuth 2.0 through a Connected App. These steps walk you through obtaining a consumer key and secret. {% hint style="success" %} This is the most secure and recommended authentication method. {% endhint %} {% stepper %} {% step %} **Create a Connected App** 1. Log in to Salesforce 2. Click the **Setup** icon (gear icon in the top right) 3. In the Quick Find box, search for **"App Manager"** 4. Click **New Connected App** {% endstep %} {% step %} **Configure the Connected App** 1. **Basic Information:** 1. **Connected App Name:** Enter a name (e.g., "Kognitos Integration") 2. **API Name:** Will auto-populate 3. **Contact Email:** Enter your email address 2. **API (Enable OAuth Settings):** 1. Check **Enable OAuth Settings** 2. **Callback URL:** Enter `https://login.salesforce.com/services/oauth2/callback` (or your specific callback URL) 3. **Selected OAuth Scopes:** Add the required scopes: 1. Access and manage your data (api) 2. Perform requests on your behalf at any time (refresh\_token, offline\_access) 3. Full access (full) - if needed 4. Click **Save** {% endstep %} {% step %} **Get Consumer Key and Consumer Secret** 1. After saving, navigate back to **Setup** → **App Manager** 2. Find your Connected App and click **View** 3. In the **API (Enable OAuth Settings)** section: 1. Copy the **Consumer Key** (also called Client ID) 2. Click **"Click to reveal"** next to **Consumer Secret** 3. Salesforce will ask you to verify your identity (via email or MFA) 4. Copy the **Consumer Secret** (also called Client Secret) {% endstep %} {% step %} **Get Your Domain** Your Salesforce **domain** is the My Domain prefix from your Salesforce URL: * **With My Domain:** `mycompany` (from `https://mycompany.my.salesforce.com`) * **Without My Domain:** `na30` (from `https://na30.salesforce.com`, where "na30" is your instance) Log into Salesforce and check your browser's address bar. {% endstep %} {% endstepper %} {% hint style="info" %} For more information, check out the Salesforce documentation: [Create a Connected App](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create.htm\&type=5). {% endhint %} ### 2. Username, Password, Security Token, and Domain This method uses username-password authentication with an API security token. {% stepper %} {% step %} **Get Your Username** Your username is the email address you use to log into Salesforce (e.g., `yourname@yourcompany.com`). {% endstep %} {% step %} **Get Your Password** This is your standard Salesforce account password. {% endstep %} {% step %} **Get Your Security Token** 1. Log in to Salesforce 2. Click your **profile icon** (top right) 3. Select **Settings** 4. In the Quick Find box, type **"Reset"** 5. Click **Reset My Security Token** 6. Click the **Reset Security Token** button 7. Check your email for the new security token 8. Copy the token from the email {% hint style="info" %} If you don't see the "Reset My Security Token" option, your organization may have IP restrictions enabled. Try this direct URL: `https://[YourDomain].my.salesforce.com/_ui/system/security/ResetApiTokenEdit` {% endhint %} {% endstep %} {% step %} **Get Your Domain** Use `login` for production, `test` for sandbox, or your My Domain prefix for custom domains. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect Using Consumer Key, Consumer Secret and Domain Connect to Salesforce using the OAuth 2.0 Client Credentials flow. | Label | Description | Type | | --------------- | ------------------------------------------------------------------------------------- | ----------- | | Consumer Key | The Consumer Key (also called Client ID) from your Connected App. | `sensitive` | | Consumer Secret | The Consumer Secret (also called Client Secret) from your Connected App. | `sensitive` | | Domain | Your Salesforce My Domain prefix (e.g., `mycompany` for mycompany.my.salesforce.com). | `text` | ### Connect Using Username, Password, Security Token and Domain Connects to a Salesforce instance using username, password, security token, and domain. | Label | Description | Type | | -------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- | | Username | The Salesforce login email (e.g., `user@company.com`). | `text` | | Password | The password associated with your Salesforce account. | `sensitive` | | Security Token | The security token emailed to you by Salesforce after a token reset. Appended to your password internally for API auth. | `sensitive` | | Domain | Use `login` for production, `test` for sandbox, or your My Domain prefix for custom domains. | `text` | ### Connect Using Username, Password and Security Token Connects to a Salesforce instance using username, password, and security token. | Label | Description | Type | | -------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- | | Username | The Salesforce login email (e.g., `user@company.com`). | `text` | | Password | The password associated with your Salesforce account. | `sensitive` | | Security Token | The security token emailed to you by Salesforce after a token reset. Appended to your password internally for API auth. | `sensitive` | ## Actions The following actions are available in the **Salesforce** integration: ### 1. Create a report Creates a report in Salesforce using the provided report metadata (name, description, report type, and optional filters). ### 2. Export a report as Excel Exports a Salesforce report as an Excel file. ### 3. Export a report as a table Exports a Salesforce report as a table for use in automations. ### 4. Retrieve reports Retrieves reports from Salesforce. Supports filtering by report name and other fields. ### 5. Send an email Sends an email through Salesforce to one or more recipients with a subject and body. {% hint style="info" %} In addition to these built-in actions, the Salesforce integration supports **custom actions** discovered from your specific Salesforce instance. This includes operations on standard and custom objects (Accounts, Opportunities, Cases, custom objects, etc.). The actions available depend on which objects you enable through the [discovery process](#discovering-actions). {% endhint %} ## Concepts ### Salesforce create report body Information sent to Salesforce to create a report. | Field Name | Description | Type | | ----------------- | --------------------------- | ------ | | `report_metadata` | The metadata of the report. | `json` | ### Salesforce report A Salesforce report object representing a set of data that meets certain criteria, displayed in an organized format. | Field Name | Description | Type | | ---------------------- | -------------------------------------------------------------- | -------------------- | | `id` | The ID of the report. | `text` | | `owner_id` | The ID of the owner of the report. | `text` | | `name` | The name of the report. | `text` | | `developer_name` | The unique name of the object in the API. | `text` | | `description` | The description of the report. Limit: 255 characters. | `optional[text]` | | `folder_name` | The name of the folder that contains the report. | `optional[text]` | | `namespace_prefix` | The namespace prefix of the report. | `optional[text]` | | `format` | The format of the report: Tabular, Summary, Matrix, or Joined. | `optional[text]` | | `is_deleted` | Whether the report is deleted. | `optional[boolean]` | | `created_date` | The date and time when the report was created. | `optional[datetime]` | | `created_by_id` | The ID of the user who created the report. | `optional[text]` | | `last_modified_date` | The date and time when the report was last modified. | `optional[datetime]` | | `last_modified_by_id` | The ID of the user who last modified the report. | `optional[text]` | | `last_referenced_date` | The date and time when the report was last referenced. | `optional[datetime]` | | `last_run_date` | The date and time when the report was last run. | `optional[datetime]` | | `last_viewed_date` | The date and time when the report was last viewed. | `optional[datetime]` | # SAP Overview of the SAP integration. {% hint style="info" %} The following documentation is for **SAP v2.6.0**. {% endhint %} ## Overview SAP is an enterprise resource planning (ERP) platform used to manage business operations across finance, logistics, and supply chain. This integration lets you discover SAP entities in your system and interact with them by reading, creating, and updating records. {% hint style="success" %} The SAP integration supports **discovery**. Once connected, you can browse available SAP services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **SAP** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific SAP services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your SAP connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the SAP services you need (e.g., "Material Document API", "Purchase Order"). Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect Using Base URL, Username and Password Connects to the SAP OData API. | Label | Description | Type | | -------- | ---------------------------------- | ----------- | | Base URL | The base URL of the SAP OData API. | `text` | | Username | The username to authenticate with. | `text` | | Password | The password to authenticate with. | `sensitive` | ## Actions The following actions are available in the **SAP** integration: ### 1. Retrieve services Retrieves the list of available SAP services. Use this to see what services are accessible through your connection before enabling specific actions. ### 2. Retrieve entities Retrieves the list of available SAP entities for a given API service. Provide the service name to see all entities you can interact with. ### 3. Upload an attachment Uploads a file attachment to a SAP business object. Requires the file, a file name, the business object type, and the linked SAP object key. {% hint style="info" %} In addition to these built-in actions, the SAP integration supports **custom actions** that are discovered from your specific SAP system. The actions available to you depend on which services you enable through the [discovery process](#discovering-actions). {% endhint %} # ServiceNow Overview of the ServiceNow integration. {% hint style="info" %} The following documentation is for **ServiceNow v2.0.0**. {% endhint %} ## Overview ServiceNow is an enterprise IT service management platform that automates and streamlines business processes. This integration enables automated ticket creation, incident management, change requests, and IT workflow automation. Improve service delivery and operational efficiency through automated IT processes. ## Setup The following integrations need to be connected to your Kognitos workspace: * **ServiceNow** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Instance, Username and Password Connects to a ServiceNow instance using the provided credentials. | Label | Description | Type | | -------- | ------------------------------------------------- | ----------- | | Instance | The instance ID for the ServiceNow instance. | `text` | | Username | The username to log in to the ServiceNow account. | `text` | | Password | The password to log in to the ServiceNow account. | `sensitive` | ## Actions The following actions are available in the **ServiceNow** integration: ### 1. Create a record in a table name Creates a new record in a ServiceNow account. ### 2. Delete some records Deletes records from ServiceNow using batch processing. ### 3. Retrieve some records from servicenow Retrieves a list of ServiceNow records based on the specified filters. ### 4. Update a record Updates a record in ServiceNow, identified by its incident number, with specified attributes and their new values. ## Concepts ### Servicenow record A dataclass for ServiceNow record. | Field Name | Description | Type | | -------------------------- | ------------------------------------------- | ------------------------ | | `short_description` | The short description of the record. | `optional[text]` | | `description` | The description of the record. | `optional[text]` | | `caller_id` | The caller ID of the record. | `optional[text]` | | `category` | The category of the record. | `optional[text]` | | `subcategory` | The subcategory of the record. | `optional[text]` | | `contact_type` | The contact type of the record. | `optional[text]` | | `assignment_group` | The assignment group of the record. | `optional[text]` | | `assigned_to` | The assigned to of the record. | `optional[text]` | | `priority` | The priority of the record. | `optional[text]` | | `severity` | The severity of the record. | `optional[text]` | | `impact` | The impact of the record. | `optional[text]` | | `urgency` | The urgency of the record. | `optional[text]` | | `location` | The location of the record. | `optional[text]` | | `business_service` | The business service of the record. | `optional[text]` | | `cmdb_ci` | The CMDB CI of the record. | `optional[text]` | | `comments` | The comments of the record. | `optional[text]` | | `additional_comments` | The additional comments of the record. | `optional[text]` | | `watch_list` | The watch list of the record. | `optional[list of text]` | | `upon_reject` | The upon reject of the record. | `optional[text]` | | `notify` | The notify of the record. | `optional[text]` | | `number` | The number of the record. | `optional[text]` | | `sys_id` | The sys ID of the record. | `optional[text]` | | `sys_created_on` | The sys created on of the record. | `optional[text]` | | `table_name` | The table name of the record. | `optional[text]` | | `parent` | The parent of the record. | `optional[text]` | | `made_sla` | The made SLA of the record. | `optional[text]` | | `sys_updated_on` | The sys updated on of the record. | `optional[text]` | | `sys_updated_by` | The sys updated by of the record. | `optional[text]` | | `approval_history` | The approval history of the record. | `optional[text]` | | `opened_by` | The opened by of the record. | `optional[text]` | | `work_end` | The work end of the record. | `optional[text]` | | `approval_set` | The approval set of the record. | `optional[text]` | | `wf_activity` | The workflow activity of the record. | `optional[text]` | | `work_notes` | The work notes of the record. | `optional[text]` | | `correlation_display` | The correlation display of the record. | `optional[text]` | | `delivery_task` | The delivery task of the record. | `optional[text]` | | `work_start` | The work start of the record. | `optional[text]` | | `additional_assignee_list` | The additional assignee list of the record. | `optional[text]` | | `calendar_duration` | The calendar duration of the record. | `optional[text]` | | `close_notes` | The close notes of the record. | `optional[text]` | | `sys_class_name` | The sys class name of the record. | `optional[text]` | | `closed_by` | The closed by of the record. | `optional[text]` | | `follow_up` | The follow up of the record. | `optional[text]` | | `company` | The company of the record. | `optional[text]` | | `reassignment_count` | The reassignment count of the record. | `optional[text]` | | `activity_due` | The activity due of the record. | `optional[text]` | | `approval` | The approval of the record. | `optional[text]` | | `sla_due` | The SLA due of the record. | `optional[text]` | | `comments_and_work_notes` | The comments and work notes of the record. | `optional[text]` | | `due_date` | The due date of the record. | `optional[text]` | | `sys_mod_count` | The sys mod count of the record. | `optional[text]` | | `sys_tags` | The sys tags of the record. | `optional[text]` | | `escalation` | The escalation of the record. | `optional[text]` | | `upon_approval` | The upon approval of the record. | `optional[text]` | | `correlation_id` | The correlation ID of the record. | `optional[text]` | | `other_fields` | Additional fields not explicitly mapped. | `optional[json]` | # Secrets Manager Overview of the Secrets Manager integration. {% hint style="info" %} The following documentation is for **Secrets Manager v1.6.4**. {% endhint %} ## Overview Provides secure storage and management of sensitive business information like passwords, API keys, and certificates. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Secrets Manager** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID Assumes a role using the provided AWS credentials. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID for the initial authentication. | `text` | | AWS Secret Access Key | The AWS Secret Access Key for the initial authentication. | `sensitive` | | AWS Region | The AWS Region for the initial authentication. | `text` | | AWS Role ARN | The ARN of the role to assume. | `text` | | AWS External ID | An optional external ID that might be required by the role's trust policy. | `sensitive` | ### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region Connects to an API using the provided API key. | Label | Description | Type | | --------------------- | ------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID | `text` | | AWS Secret Access Key | The AWS Secret Access Key | `sensitive` | | AWS Region | The AWS Region | `text` | ## Actions The following actions are available in the **Secrets Manager** integration: ### 1. Get a secret from secrets manager Get a secret from AWS Secrets Manager. ### 2. List secrets from secrets manager Get secrets available in AWS Secrets Manager. ## Concepts ### Aws secret information Represents the information of an AWS Secret. | Field Name | Description | Type | | ------------- | ------------------------------------------ | ------------------------ | | `name` | The name of the secret. | `text` | | `arn` | The ARN of the secret. | `text` | | `description` | The description of the secret. | `text` | | `tags` | A list of tags associated with the secret. | `optional[list of json]` | # SendGrid Overview of the SendGrid integration. {% hint style="info" %} The following documentation is for **SendGrid v1.0.0**. {% endhint %} ## Overview SendGrid provides a cloud-based email delivery platform for transactional and marketing email. This integration supports sending emails, managing contacts, and retrieving verified sender identities. ## Setup The following integrations need to be connected to your Kognitos workspace: * **SendGrid** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using API Key Connect to SendGrid using an API key. | Label | Description | Type | | ------- | ---------------------------------------------------------------------------------- | ----------- | | API Key | The SendGrid API key. Create one at | `sensitive` | ## Actions {% hint style="info" %} The available actions for **SendGrid** are listed in the product UI on the integration page once you create a connection. {% endhint %} # SFTP Overview of the SFTP integration. {% hint style="info" %} The following documentation is for **SFTP v1.4.11**. {% endhint %} ## Overview SFTP (Secure File Transfer Protocol) provides secure file transfer capabilities for safe data exchange. This integration enables automated file uploads, downloads, directory management, and secure data transmission workflows. Ensure secure file operations and maintain data integrity during transfers. ## Setup The following integrations need to be connected to your Kognitos workspace: * **SFTP** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Hostname, Port, Username and Password Connect to an SFTP server. | Label | Description | Type | | -------- | -------------------------------- | ----------- | | Hostname | The hostname of the SFTP server. | `text` | | Port | The port of the SFTP server. | `text` | | Username | The username for authentication. | `text` | | Password | The password for authentication. | `sensitive` | ## Actions The following actions are available in the **SFTP** integration: ### 1. Copy an item to a folder Copy an item to a folder ### 2. Create a folder in another folder Create a (folder) in another folder ### 3. Delete an item Delete an item (file or folder) ### 4. Download a file Download a file ### 5. Get a folder at a path Get a reference to a folder. ### 6. Get a root folder Get a reference to the root folder. ### 7. Get some folder's items Get items from a folder. ### 8. Move an item to a folder Move an item to a folder ### 9. Rename an item to a name Rename an item (file or folder) to a given name ### 10. Upload a file to a folder Upload a file to a folder ## Concepts ### Sftp file reference Contains all information required to identify a file within a storage system | Field Name | Description | Type | | ----------- | ----------------------------- | ------------------ | | `path` | The path of the file | `text` | | `file_name` | The name of the file | `text` | | `size` | The size of the file in bytes | `optional[number]` | | `extension` | The file extension | `optional[text]` | | `type` | The type of the SftpItem | `optional[text]` | | `name` | The name of the item | `optional[text]` | ### Sftp folder reference Contains all information required to identify a folder within a storage system | Field Name | Description | Type | | ------------- | ------------------------ | ---------------- | | `path` | The path of the folder | `text` | | `folder_name` | The name of the folder | `text` | | `type` | The type of the SftpItem | `optional[text]` | | `name` | The name of the item | `optional[text]` | # Slack Overview of the Slack integration. {% hint style="info" %} The following documentation is for **Slack v2.1.1**. {% endhint %} ## Overview The Slack integration allows users to retrieve information about Users and Channels and send messages to them. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Slack** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Token Connect to an API using the provided API key. | Label | Description | Type | | ----- | ------------------------------ | ----------- | | Token | The Slack Bot User OAuth Token | `sensitive` | ## Actions The following actions are available in the **Slack** integration: ### 1. List channels from slack List all channels from Slack. ### 2. List users from slack List all users from Slack. ### 3. Read the item's messages Read messages from a channel. ### 4. Retrieve a channel from slack Retrieve a channel from Slack. ### 5. Retrieve a user from slack Retrieve a user from Slack. ### 6. Send message to an item Send a message to a channel or user. ## Concepts ### Slack channel Represents a reference to a channel in Slack. | Field Name | Description | Type | | -------------- | ------------------------ | ------ | | `channel_id` | The ID of the channel. | `text` | | `channel_name` | The name of the channel. | `text` | ### Slack user Represents a reference to a channel in Slack. | Field Name | Description | Type | | ------------ | --------------------------------------------------- | ---------------- | | `user_id` | The ID of the user. | `text` | | `user_name` | The name of the user. | `text` | | `channel_id` | The ID of the IM channel with the current user/bot. | `optional[text]` | ### Slack message Represents a reference to a message in the Slack | Field Name | Description | Type | | ----------- | ----------------------------- | -------- | | `text` | The message. | `text` | | `timestamp` | The timestamp of the message. | `number` | | `meta` | Metadata of the message | `json` | ### Slack action block Represents an action block in Slack. | Field Name | Description | Type | | ---------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `block_id` | The ID of the block. | `optional[text]` | | `elements` | The elements of the action. | `optional[list of list of slack button element` or `slack checkbox element` or `slack date picker element` or `slack image element` or `slack markdown element?` or `slack overflow element` or `slack static select element]` | ### Slack button element Represents a button element in Slack. | Field Name | Description | Type | | ----------- | --------------------------------------- | ---------------- | | `action_id` | The ID of the button. | `text` | | `text` | The text of the button. | `text` | | `confirm` | The confirmation dialog for the button. | `optional[text]` | ### Slack static select element Represents a static select element in Slack. | Field Name | Description | Type | | ------------- | -------------------------------------------- | -------------- | | `action_id` | The ID of the select element. | `text` | | `placeholder` | The placeholder text for the select element. | `text` | | `options` | The options for the select element. | `list of text` | ### Slack date picker element Represents a date picker element in Slack. | Field Name | Description | Type | | ------------- | ----------------------------------------- | ------ | | `action_id` | The ID of the date picker. | `text` | | `placeholder` | The placeholder text for the date picker. | `text` | ### Slack overflow element Represents an overflow element in Slack. | Field Name | Description | Type | | ----------- | ------------------------------------- | -------------- | | `action_id` | The ID of the overflow element. | `text` | | `options` | The options for the overflow element. | `list of text` | ### Slack checkbox element Represents a checkbox element in Slack. | Field Name | Description | Type | | ----------- | ------------------------------------- | -------------- | | `action_id` | The ID of the checkbox element. | `text` | | `options` | The options for the checkbox element. | `list of text` | ### Slack image element Represents an image element in Slack. | Field Name | Description | Type | | ----------- | -------------------------- | ------ | | `image_url` | The URL of the image. | `text` | | `alt_text` | The alt text of the image. | `text` | ### Slack markdown element Represents a markdown element in Slack. | Field Name | Description | Type | | ---------- | --------------------------------- | ------ | | `text` | The text of the markdown element. | `text` | ### Slack context block Represents a context block in Slack. | Field Name | Description | Type | | ---------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `block_id` | The ID of the block. | `optional[text]` | | `elements` | The elements of the context block. | `optional[list of list of slack button element` or `slack checkbox element` or `slack date picker element` or `slack image element` or `slack markdown element?` or `slack overflow element` or `slack static select element]` | ### Slack divider block Represents a divider block in Slack. | Field Name | Description | Type | | ---------- | -------------------- | ---------------- | | `block_id` | The ID of the block. | `optional[text]` | ### Slack header block Represents a header block in Slack. | Field Name | Description | Type | | ---------- | ----------------------- | ---------------- | | `text` | The text of the header. | `text` | | `block_id` | The ID of the block. | `optional[text]` | ### Slack image block Represents an image block in Slack. | Field Name | Description | Type | | ----------- | --------------------------- | ---------------- | | `image_url` | The URL of the image. | `text` | | `alt_text` | The alt text for the image. | `text` | | `block_id` | The ID of the block. | `optional[text]` | ### Slack markdown block Represents a markdown block in Slack. | Field Name | Description | Type | | ---------- | ------------------------------- | ---------------- | | `text` | The text of the markdown block. | `text` | | `block_id` | The ID of the block. | `optional[text]` | ### Slack section block Represents a section block in Slack. | Field Name | Description | Type | | ----------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | The text of the section. | `optional[text]` | | `fields` | The fields of the section. | `optional[slack markdown element?` or `text]` | | `accessory` | The accessory of the section. | `optional[slack button element` or `slack checkbox element` or `slack date picker element` or `slack image element` or `slack markdown element?` or `slack overflow element` or `slack static select element]` | | `block_id` | The ID of the block. | `optional[text]` | ### Slack attachment Represents a reference to an attachment in the Slack | Field Name | Description | Type | | ----------- | --------------------------- | ------ | | `file_name` | The name of the attachment. | `text` | | `data` | The File object | `file` | # Smartsheet Overview of the Smartsheet integration. {% hint style="info" %} The following documentation is for **Smartsheet v2.0.0**. {% endhint %} ## Overview Smartsheet is a dynamic work management platform that combines spreadsheet functionality with project management features. This integration enables automated sheet updates, project tracking, resource management, and collaborative workflow automation. Improve project organization and team productivity. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Smartsheet** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Credentials ### 1. API Token These steps outline how to create a secure Smartsheet API token for accessing and interacting with the [Smartsheet API](https://developers.smartsheet.com/api/smartsheet/introduction). {% stepper %} {% step %} **Open Personal Settings** Select your account profile image at the bottom of the left navigation bar, then choose **Personal Settings**. {% endstep %} {% step %} **Go to API Access** In the Personal Settings window, navigate to the **API Access** tab. Then click on **Generate new access token**.
{% endstep %} {% step %} **Name the Token** Enter a descriptive name for the token and select **OK**. {% endstep %} {% step %} **Copy and Save the Token** Copy the generated token value and store it securely (e.g., in a password manager).\ \&#xNAN;*Note: This is the only time the token will be visible.* {% endstep %} {% step %} **Finish Setup** Select **OK** to return to the Manage API Access Tokens page, where your new token will appear by name. {% endstep %} {% endstepper %} {% hint style="info" %} For more information, check out Smartsheet's documentation [**here**](https://help.smartsheet.com/articles/2482389-generate-API-key)**.** {% endhint %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using token Authenticate with the provided token. | Label | Description | Type | | ----- | -------------------------------------------- | ----------- | | token | Smartsheet API token used for authentication | `sensitive` | ## Actions The following actions are available in the **Smartsheet** integration: ### 1. Add some content to a sheet Append the contents of a table into an existing sheet. ### 2. Get some sheet's columns Get a sheet's columns. ### 3. Get some sheet's rows Get a sheet's rows. ### 4. Get some sheets Gets all sheets. ### 5. Get some workspaces Gets all workspaces. ### 6. Insert a new column in a sheet Inserts a column in a sheet. ### 7. Insert a new row in a sheet Append a row in a sheet. ### 8. Write the content in a workspace Set the contents of a table to a new sheet. ## Concepts ### Smartsheet sheet A Sheet in Smartsheet | Field Name | Description | Type | | ---------- | --------------------- | -------- | | `id` | The id of the sheet | `number` | | `name` | The name of the sheet | `text` | ### Smartsheet column A column from a sheet. | Field Name | Description | Type | | ------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The id of the column | `optional[number]` | | `title` | The name of the column | `text` | | `column_type` | The type of the column | `enum[abstract_datetime, checkbox, contact_list, date, datetime, multi_contact_list, multi_picklist, picklist, predecessor, text_number]` | | `index` | The index of the column | `number` | ### Smartsheet row A row from a sheet. | Field Name | Description | Type | | --------------------------- | -------------------------------------------------------- | ------------------------- | | `id` | The id of the row | `optional[number]` | | `row_number` | The number of the row | `optional[number]` | | [`cells`](#smartsheet-cell) | list of the cells from the row | `list of smartsheet cell` | | `content` | a dictionary of column name to cell value in that column | `optional[json]` | | `parent_row_id` | the id of the parent row if this row is indented | `optional[number]` | ### Smartsheet cell A cell from a sheet. | Field Name | Description | Type | | -------------- | ------------------------------------ | ------------------ | | `column_id` | The id of the column for the cell | `number` | | `column_title` | The title of the column for the cell | `text` | | `row_id` | The id of the row for the cell | `optional[number]` | | `value` | The value of the cell | `any` | ### Smartsheet workspace A Workspace in Smartsheet | Field Name | Description | Type | | ---------- | ------------------------- | -------- | | `id` | The id of the workspace | `number` | | `name` | The name of the workspace | `text` | # Snowflake Overview of the Snowflake integration. {% hint style="info" %} The following documentation is for **Snowflake v2.1.0**. {% endhint %} ## Overview Enables connecting to and querying Snowflake databases. {% hint style="success" %} The Snowflake integration supports **discovery**. Once connected, you can browse available services and entities directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Snowflake** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific services and entities available in your system: {% stepper %} {% step %} **Open the connection menu** Navigate to **Integrations**, find your Snowflake connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} **Browse and enable services** Browse or search for the services you need. Toggle them on to enable them in your workspace. {% endstep %} {% step %} **Save and wait** Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Account ID, Username, Password, Database Name, Schema, Warehouse and Role Connect to a Snowflake database using the provided connection parameters. | Label | Description | Type | | ------------- | --------------------------------- | ----------- | | Account ID | Id of the Snowflake account | `text` | | Username | Username of the Snowflake account | `text` | | Password | Password of the Snowflake account | `sensitive` | | Database Name | Database Name | `text` | | Schema | Schema | `text` | | Warehouse | Warehouse of the database | `text` | | Role | Role of the db's user | `text` | # SNS Overview of the SNS integration. {% hint style="info" %} The following documentation is for **SNS v1.6.4**. {% endhint %} ## Overview Manages notifications and alerts by delivering event messages to people, applications, or systems. ## Setup The following integrations need to be connected to your Kognitos workspace: * **SNS** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID Assumes a role using the provided AWS credentials. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID for the initial authentication. | `text` | | AWS Secret Access Key | The AWS Secret Access Key for the initial authentication. | `sensitive` | | AWS Region | The AWS Region for the initial authentication. | `text` | | AWS Role ARN | The ARN of the role to assume. | `text` | | AWS External ID | An optional external ID that might be required by the role's trust policy. | `sensitive` | ### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region Connects to an API using the provided API key. | Label | Description | Type | | --------------------- | ------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID | `text` | | AWS Secret Access Key | The AWS Secret Access Key | `sensitive` | | AWS Region | The AWS Region | `text` | ## Actions The following actions are available in the **SNS** integration: ### 1. Get a topic Get an SNS topic by its ARN. ### 2. List topics Get SNS topics in the AWS account that match the filter (if any). ### 3. Publish a message to a topic Create a message in an SNS topic. ## Concepts ### Sns topic Represents an Amazon SNS topic. | Field Name | Description | Type | | -------------- | ----------------------------------------------- | ---------------- | | `arn` | The Amazon Resource Name (ARN) of the topic | `text` | | `name` | The unique name of the topic within the account | `text` | | `display_name` | The display name of the topic | `optional[text]` | # SQS Overview of the SQS integration. {% hint style="info" %} The following documentation is for **SQS v1.6.4**. {% endhint %} ## Overview Manages message queues by storing and delivering messages between systems. ## Setup The following integrations need to be connected to your Kognitos workspace: * **SQS** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID Assumes a role using the provided AWS credentials. | Label | Description | Type | | --------------------- | -------------------------------------------------------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID for the initial authentication. | `text` | | AWS Secret Access Key | The AWS Secret Access Key for the initial authentication. | `sensitive` | | AWS Region | The AWS Region for the initial authentication. | `text` | | AWS Role ARN | The ARN of the role to assume. | `text` | | AWS External ID | An optional external ID that might be required by the role's trust policy. | `sensitive` | ### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region Connects to an API using the provided API key. | Label | Description | Type | | --------------------- | ------------------------- | ----------- | | AWS Access key ID | The AWS Access Key ID | `text` | | AWS Secret Access Key | The AWS Secret Access Key | `sensitive` | | AWS Region | The AWS Region | `text` | ## Actions The following actions are available in the **SQS** integration: ### 1. Delete a message from a queue Delete a message from an SQS queue. ### 2. Get queues from sqs Get queues available in SQS. ### 3. Receive messages from a queue Get messages from an SQS queue. ### 4. Send a message to a queue Create a message in an SQS queue. ## Concepts ### Sqs message Represents a message from an Amazon SQS queue. | Field Name | Description | Type | | -------------------- | -------------------------------------------------- | ---------------- | | `message_id` | The unique identifier for the message | `text` | | `receipt_handle` | The receipt handle used to delete the message | `text` | | `queue_url` | The URL of the queue the message was received from | `text` | | `body` | The message body | `text` | | `attributes` | System attributes of the message | `optional[json]` | | `message_attributes` | Custom attributes of the message | `optional[json]` | # Todoist Overview of the Todoist integration. {% hint style="info" %} The following documentation is for **Todoist v1.0.0**. {% endhint %} ## Overview Enables managing tasks, projects, sections, labels, and comments in Todoist. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Todoist** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. #### Connect using API Token Connect to Todoist using a personal API token. | Label | Description | Type | | --------- | ------------------------------------------------------------------------------------------------------- | ----------- | | API Token | Your Todoist personal API token. Find it at Settings > Integrations > Developer in the Todoist web app. | `sensitive` | #### OAuth Authorization Code Connect to Todoist using OAuth. Provide the following from your OAuth application: | Label | Description | Type | | ------------- | ----------------------- | ----------- | | Client ID | OAuth client identifier | `text` | | Client Secret | OAuth client secret | `sensitive` | ## Actions {% hint style="info" %} The available actions for **Todoist** are listed in the product UI on the integration page once you create a connection. {% endhint %} # Twilio Overview of the Twilio integration. {% hint style="info" %} The following documentation is for **Twilio v2.1.0**. {% endhint %} ## Overview Enables interacting with and managing SMS communications via the Twilio API. Twilio provides a comprehensive communication platform, offering features such as SMS, voice calls, video, and chat. Ideal for businesses and developers seeking reliable and scalable communication solutions. This integration ensures secure and seamless access to these services. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Twilio** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using Account SID and Auth Token Connect to the Twilio API using account credentials. | Label | Description | Type | | ----------- | ----------------------------------------- | ----------- | | Account SID | The Account SID from your Twilio account. | `text` | | Auth Token | The Auth Token from your Twilio account. | `sensitive` | ## Actions The following actions are available in the **Twilio** integration: ### 1. Read some SMS messages Get SMS messages from the Twilio API. ### 2. Send an SMS message Send an SMS message using the Twilio API. ## Concepts ### Twilio sms message SMS message data model.An SMS (Short Message Service) message. Represents a text communication sent over a cellular network, typically between mobile phones. | Field Name | Description | Type | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | `sid` | The unique, Twilio-provided string that identifies the Message resource. | `optional[text]` | | `body` | The text content of the message | `optional[text]` | | `num_segments` | The number of segments that make up the complete message. SMS message bodies that exceed the [character limit](https://www.twilio.com/docs/glossary/what-sms-character-limit) are segmented and charged as multiple messages. Note: For messages sent via a Messaging Service, `num_segments` is initially `0`, since a sender hasn't yet been assigned | `optional[text]` | | `sender_number` | The sender's phone number (in [E.164](https://en.wikipedia.org/wiki/E.164) format), [alphanumeric sender ID](https://www.twilio.com/docs/sms/quickstart), [Wireless SIM](https://www.twilio.com/docs/iot/wireless/programmable-wireless-send-machine-machine-sms-commands), [short code](https://www.twilio.com/en-us/messaging/channels/sms/short-codes), or [channel address](https://www.twilio.com/docs/messaging/channels) (e.g., `whatsapp:+15554449999`). For incoming messages, this is the number or channel address of the sender. For outgoing messages, this value is a Twilio phone number, alphanumeric sender ID, short code, or channel address from which the message is sent | `optional[text]` | | `recipient_number` | The recipient's phone number (in [E.164](https://en.wikipedia.org/wiki/E.164) format) or [channel address](https://www.twilio.com/docs/messaging/channels) (e.g. `whatsapp:+15552229999`) | `optional[text]` | | `price` | The amount billed for the message in the currency specified by `price_unit`. The `price` is populated after the message has been sent/received, and may not be immediately available. View the [Pricing page](https://www.twilio.com/en-us/pricing) for more details. | `optional[number]` | | `account_sid` | The SID of the [Account](https://www.twilio.com/docs/iam/api/account) associated with the Message resource | `text` | | `num_media` | The number of media files associated with the Message resource. | `number` | | `status` | The status of the message, for more information about possible statuses see [Message Status](https://www.twilio.com/docs/messaging/api/message-resource#message-status-values) | `optional[text]` | | `messaging_service_sid` | The SID of the [Messaging Service](https://www.twilio.com/docs/messaging/api/service-resource) associated with the Message resource. A unique default value is assigned if a Messaging Service is not used. | `text` | | `date_sent` | The [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) timestamp (in GMT) of when the Message was sent. For an outgoing message, this is when Twilio sent the message. For an incoming message, this is when Twilio sent the HTTP request to your incoming message webhook URL. | `optional[datetime]` | | `date_created` | The [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) timestamp (in GMT) of when the Message resource was created | `optional[datetime]` | | `date_updated` | The [RFC 2822](https://datatracker.ietf.org/doc/html/rfc2822#section-3.3) timestamp (in GMT) of when the Message resource was last updated | `optional[datetime]` | | `price_unit` | The currency in which `price` is measured, in [ISO 4127](https://www.iso.org/iso/home/standards/currency_codes.htm) format (e.g. `usd`, `eur`, `jpy`). | `text` | | `error_code` | The [error code](https://www.twilio.com/docs/api/errors) returned if the Message `status` is `failed` or `undelivered`. If no error was encountered, the value is `null`. | `optional[number]` | | `error_message` | The description of the `error_code` if the Message `status` is `failed` or `undelivered`. If no error was encountered, the value is `null`. | `optional[text]` | # Zendesk Overview of the Zendesk integration. {% hint style="info" %} The following documentation is for **Zendesk v3.3.0**. {% endhint %} ## Overview Zendesk integration that enables users to create, update, delete, and get tickets in Zendesk. This integration provides comprehensive ticket management capabilities including creating tickets with custom properties, updating ticket status and priority, deleting tickets, and retrieving tickets through search or direct ID lookup. It also supports comment management with optional file attachments and includes user search functionality for accessing Zendesk user information. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Zendesk** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements. ### Connect using subdomain, email and token Connects to Zendesk using email and API token authentication. | Label | Description | Type | | --------- | ----------------------------------------------- | ------ | | subdomain | The subdomain of your Zendesk account. | `text` | | email | The email associated with your Zendesk account. | `text` | | token | The API token from Zendesk for authentication. | `text` | ## Actions The following actions are available in the **Zendesk** integration: ### 1. Add a comment to a ticket Adds a comment to an existing ticket in Zendesk with an optional single file attachment. ### 2. Create a ticket in zendesk Creates a new ticket in Zendesk with the specified properties. ### 3. Delete a ticket in zendesk Deletes a specified ticket in Zendesk. ### 4. Download an attachment Downloads an attachment from Zendesk. ### 5. Get a ticket in zendesk Retrieves a specific ticket from Zendesk by its ID using direct API access. ### 6. Get a user in zendesk Retrieves a specific user from Zendesk by their ID. ### 7. Get some ticket's audits in zendesk Retrieves all audits for a specific ticket in Zendesk. ### 8. Get some ticket's comments in zendesk Retrieves all comments for a specific ticket in Zendesk. ### 9. Get some users in zendesk Retrieves users from Zendesk using search functionality with optional filter expressions. ### 10. Get ticket fields in zendesk Retrieves all available ticket field definitions from Zendesk. ### 11. Search some tickets in zendesk Retrieves tickets from Zendesk using search functionality with optional filter expressions. ### 12. Update a ticket in zendesk Updates a specific ticket in Zendesk with the provided information. ## Concepts ### Zendesk ticket A ticket in Zendesk. | Field Name | Description | Type | | ---------------------------- | ----------------------------------------------------------------- | ------------------------ | | `id` | The ID of the ticket. | `optional[number]` | | [`assignee`](#zendesk-user) | The assignee of the ticket. | `optional[zendesk user]` | | `created_at` | The creation date of the ticket. | `optional[datetime]` | | `custom_fields` | List of custom fields as dictionaries with 'id' and 'value' keys. | `optional[list of json]` | | `description` | The description of the ticket. | `optional[text]` | | `due_at` | The due date of the ticket. | `optional[datetime]` | | `priority` | The priority of the ticket. | `optional[text]` | | `requester_id` | The ID of the requester. | `optional[number]` | | [`submitter`](#zendesk-user) | The submitter of the ticket. | `optional[zendesk user]` | | `status` | The status of the ticket. | `optional[text]` | | `subject` | The subject of the ticket. | `optional[text]` | | `tags` | The tags of the ticket. | `optional[list of text]` | | `type` | The type of the ticket. | `optional[text]` | | `url` | The URL of the ticket. | `optional[text]` | ### Zendesk user A user in Zendesk. | Field Name | Description | Type | | ---------- | ---------------------- | ------------------ | | `id` | The ID of the user. | `optional[number]` | | `email` | The email of the user. | `optional[text]` | | `name` | The name of the user. | `optional[text]` | ### Zendesk comment A comment in Zendesk. | Field Name | Description | Type | | ------------------------------------ | ----------------------------------------------------------------- | -------------------------------------- | | `id` | The ID of the comment. | `optional[number]` | | `body` | The content/text of the comment. | `optional[text]` | | [`author`](#zendesk-user) | The user who created the comment. | `optional[zendesk user]` | | `created_at` | When the comment was created. | `optional[datetime]` | | `public` | Whether the comment is public (true) or an internal note (false). | `optional[boolean]` | | `type` | The type of comment (Comment, VoiceComment, etc.). | `optional[text]` | | [`attachments`](#zendesk-attachment) | List of ZendeskAttachment objects. | `optional[list of zendesk attachment]` | ### Zendesk attachment An attachment in Zendesk. | Field Name | Description | Type | | -------------- | ------------------------------------------- | ------------------ | | `id` | The ID of the attachment. | `optional[number]` | | `file_name` | The name of the file. | `optional[text]` | | `content_url` | The URL to download the attachment content. | `optional[text]` | | `content_type` | The MIME type of the attachment. | `optional[text]` | | `size` | The size of the attachment in bytes. | `optional[number]` | ### Zendesk audit An audit record for a ticket in Zendesk. | Field Name | Description | Type | | ------------ | ------------------------------------------------------- | -------------------------------- | | `id` | The ID of the audit. | `optional[number]` | | `ticket_id` | The ID of the ticket this audit belongs to. | `optional[number]` | | `created_at` | When the audit was created. | `optional[datetime]` | | `author_id` | The ID of the user who performed the action. | `optional[number]` | | `metadata` | Additional metadata about the audit. | `optional[json]` | | `events` | List of events in this audit (changes, comments, etc.). | `optional[list of list of any?]` | ### Zendesk ticket field A custom field definition for Zendesk tickets. | Field Name | Description | Type | | ------------- | ----------------------------------------------------------------- | ---------------- | | `id` | The ID of the ticket field. | `number` | | `title` | The human-readable title of the field. | `optional[text]` | | `type` | The type of the field (text, textarea, checkbox, dropdown, etc.). | `optional[text]` | | `description` | The description of the field. | `optional[text]` | | `value` | The actual value for this field on a specific ticket. | `optional[any?]` | # Zoho CRM Overview of the Zoho CRM integration. {% hint style="info" %} The following documentation is for **Zoho CRM v1.0.0**. {% endhint %} ## Overview This integration allows you to discover Zoho CRM modules (including custom modules) and interact with their records by listing, creating, updating, and deleting them. {% hint style="success" %} The Zoho CRM integration supports **discovery**. Once connected, you can browse available modules directly from Kognitos, then enable the specific actions your automations need. See [Custom Actions](/guides/platform/integrations#custom-actions) for setup instructions. {% endhint %} ## Setup The following integrations need to be connected to your Kognitos workspace: * **Zoho CRM** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} #### Navigate Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} #### Find Search for the integration and click on it. {% endstep %} {% step %} #### Connect Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} #### Configure Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ### Discovering Actions After connecting, you can discover and enable the specific modules available in your Zoho CRM account: {% stepper %} {% step %} #### Open the connection menu Navigate to **Integrations**, find your Zoho CRM connection, and click the three-dot menu **⋯** next to the connection name. Select **Configure Actions**. {% endstep %} {% step %} #### Browse and enable modules Browse or search for the modules you need (including any custom modules). Toggle them on to enable them in your workspace. {% endstep %} {% step %} #### Save and wait Click **Save** to apply your configuration. Allow 1-2 minutes for Kognitos to complete the discovery process. Once finished, the enabled actions become available in your drafts and automations. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. #### OAuth Authorization Code Connects to Zoho CRM using OAuth. Provide the **Client ID** and **Client Secret** from a self-client or web application you create in the [Zoho API Console](https://api-console.zoho.com/), then complete the **Continue with Zoho** flow. | Label | Description | Type | | ------------- | -------------------------------------------------- | ----------- | | Client ID | OAuth client identifier from the Zoho API Console. | `text` | | Client Secret | OAuth client secret from the Zoho API Console. | `sensitive` | ## Actions {% hint style="info" %} The available actions for **Zoho CRM** depend on which modules you enable through the discovery process described above. Listing, retrieval, creation, update, and deletion are supported across the discovered modules. {% endhint %} # ZIP Overview of the ZIP integration. {% hint style="info" %} The following documentation is for **ZIP v1.8.0**. {% endhint %} ## Overview Enables compressing and decompressing ZIP archives. ## Setup The following integrations need to be connected to your Kognitos workspace: * **ZIP** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Actions The following actions are available in the **ZIP** integration: ### 1. Check file existence in a zip Check if a specific file exists in a ZIP archive. ### 2. Compress files to zip Create a ZIP archive from multiple files. ### 3. Decompress a zip file Extract all files from a ZIP archive. ### 4. Extract a file from zip Extract a specific file from a ZIP archive. ### 5. Get the file count of a zip Get the number of files in a ZIP archive. ### 6. List files in a zip Get the list of filenames in a ZIP archive. # Zoom Overview of the Zoom integration. {% hint style="info" %} The following documentation is for **Zoom v1.0.1**. {% endhint %} ## Overview Zoom is a video communications platform for meetings, webinars, and team collaboration. This integration lets you create and manage meetings, list users, access recordings, and work with webinars from Kognitos. ## Setup The following integrations need to be connected to your Kognitos workspace: * **Zoom** ### Steps Follow these steps to connect the integration in Kognitos: {% stepper %} {% step %} **Navigate** Using the left navigation menu, go to **Integrations** → **Explore Integrations**. {% endstep %} {% step %} **Find** Search for the integration and click on it. {% endstep %} {% step %} **Connect** Click on **Connect** to add a connection to the integration. {% endstep %} {% step %} **Configure** Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on **Connect**. {% endstep %} {% endstepper %} ## Authentication Use one of the following authentication methods to connect this integration in Kognitos. ### OAuth Authorization Code Connect to Zoom with your own OAuth client. | Label | Description | Type | | ------------- | ----------------------- | ----------- | | Client ID | OAuth client identifier | `text` | | Client Secret | OAuth client secret | `sensitive` | ### Server-to-Server OAuth Connect to Zoom using Server-to-Server OAuth credentials. | Label | Description | Type | | ------------- | -------------------------------------------------------------------------------------------- | ----------- | | Account ID | The Zoom Account ID, found on the Server-to-Server OAuth app page under **App Credentials**. | `text` | | Client ID | The Client ID of your Server-to-Server OAuth app, found under **App Credentials**. | `text` | | Client Secret | The Client Secret of your Server-to-Server OAuth app, found under **App Credentials**. | `sensitive` | ## Actions The following actions are available in the **Zoom** integration: ### 1. Create a meeting Create a Zoom meeting. ### 2. Create a webinar Create a Zoom webinar. ### 3. Delete a meeting Delete a Zoom meeting. ### 4. Delete a webinar Delete a Zoom webinar. ### 5. End a meeting End an active Zoom meeting. ### 6. Get the current user Retrieve the current Zoom user. ### 7. Get a meeting Retrieve a Zoom meeting. ### 8. Get meeting participants Retrieve participants for a Zoom meeting. ### 9. Get meeting recordings Retrieve recordings for a Zoom meeting. ### 10. Get meetings Retrieve Zoom meetings. ### 11. Get recordings Retrieve Zoom cloud recordings. ### 12. Get users Retrieve Zoom users. ### 13. Get a webinar Retrieve a Zoom webinar. ### 14. Get webinars Retrieve Zoom webinars. ### 15. Update a meeting Update an existing Zoom meeting. # Kognitos MCP Server Connect any AI assistant to Kognitos using the Model Context Protocol. The Kognitos MCP Server lets AI assistants (Claude Desktop, Claude Code, Claude.ai, and any other [Model Context Protocol](https://modelcontextprotocol.io) client) interact with your Kognitos workspace. Your AI assistant can list automations, start runs, inspect exceptions, manage schedules, and more, using natural language. ## Server URL ``` https://mcp.us-1.kognitos.com/ ``` The server uses the Streamable HTTP transport. MCP clients connect directly to this URL - no server-side installation is required. {% hint style="info" %} To connect an AI assistant, see [Connect an AI Client](/guides/mcp/clients). {% endhint %} ## Authentication The server supports two authentication methods. Use the one that fits how you plan to use it. ### OAuth 2.1 (Recommended) When you connect from an interactive client, the client opens your browser to the Kognitos login screen. After you sign in and approve the connection, the browser redirects back to the client, which receives a short-lived token for subsequent requests. OAuth is the recommended path for everyday use in Claude Desktop, Claude Code, and Claude.ai. Your client handles token refresh automatically, and access is scoped to your user account and permissions. {% hint style="info" %} OAuth tokens are short-lived and automatically refreshed by your client. Prefer OAuth over API keys for interactive clients. {% endhint %} ### API Key For CI pipelines, scripts, or other non-interactive use cases, authenticate with a Kognitos API key passed in the `Authorization` header: ``` Authorization: Bearer YOUR_API_KEY ``` See [API Keys](https://docs.kognitos.com/guides/api-reference/api-keys) for instructions on creating and scoping an API key. {% hint style="warning" %} Your AI assistant acts on content it reads. Avoid connecting the MCP server to automations that ingest untrusted input without review. A malicious document or message could attempt to instruct the assistant to take actions on your behalf. {% endhint %} ## Tools The following tools are available through the MCP server. Related actions are grouped together, with read and write actions for a resource exposed as separate tools (for example, `kognitos_threads` for read and `kognitos_manage_thread` for write). Your AI client selects the right tool and action based on your request. ### Organizations and Workspaces | Tool | Actions | Description | | ----------------------------- | ------- | ----------------------------------- | | `kognitos_list_organizations` | - | List organizations you belong to. | | `kognitos_list_workspaces` | - | List workspaces in an organization. | ### Automations | Tool | Actions | Description | | ---------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kognitos_automations` | `list`, `get`, `query` | Browse, inspect, or query automations by stage. | | `kognitos_create_automation` | - | Create a new automation from a natural language description. | | `kognitos_threads` | `get`, `list`, `list_messages` | Read thread state and list messages in a thread. | | `kognitos_manage_thread` | `create`, `send_message`, `stop` | Create threads, send messages to the AI agent, or stop a thread. | | `kognitos_manage_automation` | `publish`, `activate`, `deactivate`, `delete`, `discard_draft`, `rename`, `fork` | Manage the automation lifecycle. `delete` removes the published version (preserves the draft if present); `discard_draft` removes the in-progress draft only. | | `kognitos_invoke_automation` | - | Start a run of an automation. | ### Runs | Tool | Actions | Description | | ---------------------- | ----------------------------------------------- | -------------------------------------------------------------- | | `kognitos_runs` | `list`, `get`, `get_run_outputs`, `list_events` | Monitor run status, retrieve outputs, and view execution logs. | | `kognitos_control_run` | `pause`, `continue` | Pause a running automation or resume a paused one. | ### Scheduling | Tool | Actions | Description | | -------------------------- | ------------------------------------------------- | ----------------------------------------------------------------- | | `kognitos_get_schedule` | - | Get the current schedule for an automation. | | `kognitos_manage_schedule` | `create`, `update`, `enable`, `disable`, `delete` | Create, update, enable/disable, or delete an automation schedule. | ### Exceptions | Tool | Actions | Description | | ----------------------------- | ----------------------------------------------------------------- | --------------------------------------------------- | | `kognitos_inspect_exceptions` | `list`, `get`, `count`, `list_events`, `get_guide`, `list_guides` | Inspect exceptions and view troubleshooting guides. | | `kognitos_reply_to_exception` | - | Send a message to the exception resolution agent. | | `kognitos_manage_exceptions` | `archive`, `unarchive`, `assign` | Archive, unarchive, or assign exceptions. | ### Integrations | Tool | Actions | Description | | ---------------- | ----------------------------------------------------- | ------------------------------------------------ | | `kognitos_books` | `search`, `list_workspace_books`, `search_procedures` | Discover integrations and search for procedures. | ### Analytics | Tool | Actions | Description | | -------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | | `kognitos_analytics` | `run_stats`, `insights`, `exception_insights` | Platform health: run statistics, org-level insights, and exception metrics. | ### Files | Tool | Actions | Description | | ---------------------- | --------------------------- | --------------------------------------------------------------- | | `kognitos_read_file` | `get_metadata`, `read_file` | Inspect file metadata or read file content inline. | | `kognitos_upload_file` | - | Upload a file (base64 or pre-signed URL) for automation inputs. | ## Example prompts Once connected, you can ask your AI assistant to do things in plain English. A few to try: * **"List the automations in my Finance workspace and show me which ones failed in the last 24 hours."** The assistant calls `kognitos_list_workspaces`, then `kognitos_automations`, then `kognitos_runs` to find failed runs. * **"Create a new automation that reads invoices from an S3 bucket and posts totals to Slack."** The assistant calls `kognitos_create_automation` and streams progress as the Kognitos AI builds the automation. * **"Run my 'Daily Invoice Sync' automation and let me know when it finishes."** The assistant calls `kognitos_invoke_automation` and then polls `kognitos_runs` for status. * **"Show me any open exceptions assigned to me and help me triage the oldest one."** The assistant calls `kognitos_inspect_exceptions` and walks you through the troubleshooting guide. # Connect an AI Client Set up Claude Desktop, Claude Code, Claude.ai, or ChatGPT to use the Kognitos MCP server. Follow the steps for your AI client below. All clients connect to the same server URL: `https://mcp.us-1.kognitos.com/`. ## Prerequisites * A Kognitos account * One of the supported MCP clients installed * An [API key](https://docs.kognitos.com/guides/api-reference/api-keys) *(only if you plan to authenticate with a key instead of OAuth)* ## Claude Desktop {% stepper %} {% step %} **Open the configuration file** On your machine, open the Claude Desktop configuration file: * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` If the file does not exist, create it with an empty `{}` object. {% endstep %} {% step %} **Add the Kognitos server** Add the `kognitos` entry to the `mcpServers` object. Choose the tab that matches your preferred authentication method. {% tabs %} {% tab title="OAuth" %} ```json { "mcpServers": { "kognitos": { "url": "https://mcp.us-1.kognitos.com/", "oauth": { "callbackPort": 3777 } } } } ``` {% endtab %} {% tab title="API Key" %} ```json { "mcpServers": { "kognitos": { "url": "https://mcp.us-1.kognitos.com/", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} **Restart Claude Desktop** Quit and reopen Claude Desktop. The first time you use a Kognitos tool with the OAuth variant, your browser will open to the Kognitos login screen. Sign in and approve the connection. {% endstep %} {% step %} **Verify the connection** In a new Claude Desktop chat, send: > *List my Kognitos workspaces.* Claude will use the `kognitos_list_workspaces` tool to respond. If the tool does not appear to run, see the sign-in note below. {% endstep %} {% endstepper %} {% hint style="info" %} If your OAuth session expires, Claude Desktop will prompt you to sign in again the next time you use a Kognitos tool. No configuration change is needed. {% endhint %} ## Claude Code {% stepper %} {% step %} **Add the MCP server** Run one of the following commands from your terminal. {% tabs %} {% tab title="OAuth" %} ```bash claude mcp add --transport http --callback-port 3777 kognitos https://mcp.us-1.kognitos.com/ ``` {% endtab %} {% tab title="API Key" %} ```bash claude mcp add --transport http kognitos https://mcp.us-1.kognitos.com/ \ --header "Authorization: Bearer YOUR_API_KEY" ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} **Verify the connection** List your configured MCP servers to confirm `kognitos` is registered: ```bash claude mcp list ``` Then start Claude Code and send: > *List my Kognitos workspaces.* If you chose OAuth, Claude Code opens your browser on the first tool call so you can sign in and approve the connection. {% endstep %} {% endstepper %} {% hint style="info" %} The `--callback-port 3777` flag (or `callbackPort` in Claude Desktop) tells the client which port to use for the OAuth callback. This port is pre-registered with the Kognitos authentication service. Omitting it may cause a "Callback URL mismatch" error during sign-in. {% endhint %} ## Claude.ai {% stepper %} {% step %} **Open Connectors** In Claude.ai, open **Settings** → **Connectors**. {% endstep %} {% step %} **Add the Kognitos connector** Click **Add custom connector** and fill in the form: * **Name**: `Kognitos` * **Remote MCP server URL**: `https://mcp.us-1.kognitos.com/` Leave the other fields at their defaults. The server URL is the only value you need to provide. Claude.ai discovers the rest automatically. {% endstep %} {% step %} **Sign in to Kognitos** Click **Connect**. Claude.ai will redirect you to the Kognitos login screen. Sign in with your Kognitos account and approve the connection. You do not share any Kognitos credentials with Claude.ai. Authentication happens in your browser, and Claude.ai only receives a short-lived access token tied to your user account. {% endstep %} {% step %} **Verify the connection** Start a new chat, enable the **Kognitos** connector in the chat composer, and send: > *List my Kognitos workspaces.* > {% endstep %} > {% endstepper %} ## ChatGPT {% stepper %} {% step %} **Enable Developer mode** In ChatGPT, open **Settings** → **Connectors** → **Advanced settings** and turn on **Developer mode**. This is required to add custom MCP connectors. Return to the **Connectors** page when done. {% endstep %} {% step %} **Add the Kognitos connector** Click **Create** and fill in the form: * **Name**: `Kognitos` * **MCP server URL**: `https://mcp.us-1.kognitos.com/` * **Authentication**: `OAuth` Click **Create** to save the connector. {% endstep %} {% step %} **Sign in to Kognitos** Click **Connect** on the new connector. ChatGPT will redirect you to the Kognitos login screen. Sign in with your Kognitos account and approve the connection. You do not share any Kognitos credentials with ChatGPT. Authentication happens in your browser, and ChatGPT only receives a short-lived access token tied to your user account. {% endstep %} {% step %} **Verify the connection** Start a new chat with the **Kognitos** connector enabled and send: > *List my Kognitos workspaces.* > {% endstep %} > {% endstepper %} {% hint style="info" %} ChatGPT caches OAuth client registration for each connector. If you change authentication settings on the server side, or if a previously working connector starts returning "unauthorized", remove the connector and re-add it to force a fresh registration. {% endhint %} ## Other MCP clients The Kognitos MCP server uses the standard Streamable HTTP transport and works with any compliant MCP client, including Cursor, Visual Studio Code, and Windsurf. In the client's MCP configuration, use: * **Server URL**: `https://mcp.us-1.kognitos.com/` * **Transport**: Streamable HTTP * **Authentication**: OAuth (automatic discovery) or an `Authorization: Bearer YOUR_API_KEY` header * **OAuth callback port**: `3777` (configure in your client's MCP settings when using OAuth) Refer to your client's documentation for where to enter these values. # 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 ``` {% 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) for setup instructions. ## Quick Start ### Prerequisites * A Kognitos account with at least one published automation * An [API Key](/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" ``` ## 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 | # API Keys Create and manage API keys for authenticating with the Kognitos REST API. ## Overview **API keys** (Personal Access Tokens) let you authenticate with the Kognitos REST API. Each key is scoped to specific workspaces and permissions, giving you control over what API consumers can access. ## Creating an API Key {% stepper %} {% step %} **Open API Keys** Click on your name or profile avatar in the bottom-left corner to open the user menu. Then select **API Keys**. {% endstep %} {% step %} **Create a New Key** Click **Create API Key**. Fill in the following: * **Name**: A descriptive name (e.g., "CI Pipeline", "Monitoring Dashboard") * **Expiration**: How long the key is valid (7 days, 30 days, 60 days, 90 days, 180 days, or 1 year) * **Scope**: Which workspaces the key can access * **Permissions**: What the key can do
{% endstep %} {% step %} **Choose Permissions** Select a permission level: | Permission | Access | | -------------- | --------------------------------------------------------------------------------------------- | | **All** | Full read and write access to all API endpoints, including run archiving | | **Read only** | Read access only (list, get, query endpoints) | | **Restricted** | Custom per-resource permissions (includes granular control over run management and archiving) | {% hint style="info" %} When selecting **Restricted**, you can expand each permission group and toggle individual permissions on or off. {% endhint %} {% endstep %} {% step %} **Set the Scope** Choose which workspaces this key can access: * **All Workspaces**: Access to every workspace in the organization * **Specific Workspaces**: Select one or more workspaces from the list {% endstep %} {% step %} **Save Your Key** Click **Create**. Your API key will be displayed once. Copy it and store it securely.
{% hint style="warning" %} **Save your key now.** You will not be able to view it again. If you lose it, you will need to create a new one. {% endhint %} {% endstep %} {% endstepper %} ## Using Your API Key Include the key in the `Authorization` header of every API request: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ "https://app.us-1.kognitos.com/api/v1/me/organizations" ``` ## Managing API Keys From the **API Keys** page, you can view all keys with their name, key prefix, scope, and creation date.
Use the menu on each row to **edit** a key's name, permissions, or scope, or **delete** a key to immediately revoke access. {% hint style="warning" %} Deleting an API key immediately disables it. Any systems using that key will lose access. {% endhint %} ## Limits * Up to **10 API keys** per organization * Keys are scoped to the **organization** where they were created * Expired keys are automatically disabled ## Checking Your Permissions You can verify what permissions your API key grants by calling the [Current User Permissions](/guides/api-reference/api-reference#current-user-permissions) endpoint. This returns the effective permissions for the authenticated user in a given organization and workspace. ## Best Practices * **Use descriptive names** so you know which system uses each key * **Set the shortest expiration** that meets your needs * **Use restricted permissions** to limit access to only what each consumer needs * **Rotate keys regularly** by creating a new key before deleting the old one * **Never commit keys to source control**. Use environment variables or a secrets manager. # Organizations Manage organizations, users, roles, invitations, and preferences. ## GET /api/v1/organizations/{organization\_id} > Get Organization ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Organization":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the organization.\nFormat: organizations/{organization_id}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the organization."},"logo_data_uri":{"type":"string","title":"The organization logo as a data URI following RFC 2397.\nFormat: data:[][;encoding],\nExample: data:image/png;encoding,"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was last updated.","readOnly":true},"owner_display_name":{"type":"string","description":"The display name of the organization owner.","readOnly":true},"owner_email":{"type":"string","description":"The email address of the organization owner.","readOnly":true}},"description":"An Organization is the top-level resource container.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}":{"get":{"summary":"Get Organization","operationId":"GetOrganization","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Organization"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/me/organizations > Current User Organizations ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserOrganizationsResponse":{"type":"object","properties":{"user_organizations":{"type":"array","items":{"$ref":"#/components/schemas/v1Organization"},"description":"The list of organizations the current user is a member of."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`CurrentUserOrganizations` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing organizations for the current user."},"v1Organization":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the organization.\nFormat: organizations/{organization_id}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the organization."},"logo_data_uri":{"type":"string","title":"The organization logo as a data URI following RFC 2397.\nFormat: data:[][;encoding],\nExample: data:image/png;encoding,"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the organization was last updated.","readOnly":true},"owner_display_name":{"type":"string","description":"The display name of the organization owner.","readOnly":true},"owner_email":{"type":"string","description":"The email address of the organization owner.","readOnly":true}},"description":"An Organization is the top-level resource container.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me/organizations":{"get":{"summary":"Current User Organizations","operationId":"CurrentUserOrganizations","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserOrganizationsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"page_size","description":"The maximum number of organizations to return.\nIf unspecified, at most 50 organizations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous `ListCurrentUserOrganizations` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListCurrentUserOrganizations` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nExample: \"title='My Organization'\"","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/preferences > Get Organization Preferences ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1OrganizationPreferences":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the organization preferences.\nFormat: `organizations/{organization}/preferences`"},"support_team_access":{"type":"boolean","description":"Support team access to workspaces in the organization for debugging issues."},"general":{"$ref":"#/components/schemas/v1GeneralPreferences"}},"description":"Represents organization-specific settings or preferences."},"v1GeneralPreferences":{"type":"object","properties":{"time_zone":{"type":"string","description":"The time zone preference.\nShould be an IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\", \"UTC\")."},"time_format":{"$ref":"#/components/schemas/v1TimeFormat"},"date_format":{"$ref":"#/components/schemas/v1DateFormat"},"decimal_symbol":{"$ref":"#/components/schemas/v1DecimalSymbol"},"decimal_places":{"type":"integer","format":"int32","description":"The number of digits after decimal point."},"measurement_system":{"$ref":"#/components/schemas/v1MeasurementSystem"}},"description":"General preferences for display and formatting.\nUsed by both workspace and organization preferences."},"v1TimeFormat":{"type":"string","enum":["TIME_FORMAT_UNSPECIFIED","TIME_FORMAT_12_HOUR","TIME_FORMAT_24_HOUR"],"default":"TIME_FORMAT_UNSPECIFIED","description":"Supported time formats.\n\n - TIME_FORMAT_UNSPECIFIED: Unspecified time format.\n - TIME_FORMAT_12_HOUR: 12-hour format (1:00 PM).\n - TIME_FORMAT_24_HOUR: 24-hour format (13:00)."},"v1DateFormat":{"type":"string","enum":["DATE_FORMAT_UNSPECIFIED","DATE_FORMAT_DD_MM_YYYY_SLASH","DATE_FORMAT_MM_DD_YYYY_SLASH","DATE_FORMAT_YYYY_MM_DD_DASH","DATE_FORMAT_DD_MM_YYYY_DASH","DATE_FORMAT_MM_DD_YYYY_DASH","DATE_FORMAT_YYYY_MM_DD_SLASH","DATE_FORMAT_DD_MM_YYYY_DOT","DATE_FORMAT_MM_DD_YYYY_DOT","DATE_FORMAT_YYYY_MM_DD_DOT","DATE_FORMAT_DD_MMM_YYYY","DATE_FORMAT_MMM_DD_YYYY","DATE_FORMAT_DD_MMMM_YYYY","DATE_FORMAT_MMMM_DD_YYYY"],"default":"DATE_FORMAT_UNSPECIFIED","description":"Supported date formats.\n\n - DATE_FORMAT_UNSPECIFIED: Unspecified date format.\n - DATE_FORMAT_DD_MM_YYYY_SLASH: DD/MM/YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_SLASH: MM/DD/YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DASH: YYYY-MM-DD format (ISO 8601).\n - DATE_FORMAT_DD_MM_YYYY_DASH: DD-MM-YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_DASH: MM-DD-YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_SLASH: YYYY/MM/DD format.\n - DATE_FORMAT_DD_MM_YYYY_DOT: DD.MM.YYYY format (European style).\n - DATE_FORMAT_MM_DD_YYYY_DOT: MM.DD.YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DOT: YYYY.MM.DD format.\n - DATE_FORMAT_DD_MMM_YYYY: DD MMM YYYY format (e.g., 15 Jan 2024).\n - DATE_FORMAT_MMM_DD_YYYY: MMM DD, YYYY format (e.g., Jan 15, 2024).\n - DATE_FORMAT_DD_MMMM_YYYY: DD MMMM YYYY format (e.g., 15 January 2024).\n - DATE_FORMAT_MMMM_DD_YYYY: MMMM DD, YYYY format (e.g., January 15, 2024)."},"v1DecimalSymbol":{"type":"string","enum":["DECIMAL_SYMBOL_UNSPECIFIED","DECIMAL_SYMBOL_PERIOD","DECIMAL_SYMBOL_COMMA"],"default":"DECIMAL_SYMBOL_UNSPECIFIED","description":"Supported decimal symbols.\n\n - DECIMAL_SYMBOL_UNSPECIFIED: Unspecified decimal symbol.\n - DECIMAL_SYMBOL_PERIOD: Period (.) as decimal separator.\n - DECIMAL_SYMBOL_COMMA: Comma (,) as decimal separator."},"v1MeasurementSystem":{"type":"string","enum":["MEASUREMENT_SYSTEM_UNSPECIFIED","MEASUREMENT_SYSTEM_METRIC","MEASUREMENT_SYSTEM_IMPERIAL"],"default":"MEASUREMENT_SYSTEM_UNSPECIFIED","description":"Supported measurement systems.\n\n - MEASUREMENT_SYSTEM_UNSPECIFIED: Unspecified measurement system.\n - MEASUREMENT_SYSTEM_METRIC: Metric system.\n - MEASUREMENT_SYSTEM_IMPERIAL: Imperial system."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/preferences":{"get":{"summary":"Get Organization Preferences","operationId":"GetOrganizationPreferences","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1OrganizationPreferences"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/invitations/{invitation\_id} > Get Invitation ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Invitation":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the invitation.\nFormat: organizations/{organization}/invitations/{invitation}"},"organization_display_name":{"type":"string","description":"The organization display name."},"workspace_id":{"type":"string","description":"The workspace ID (not set if org-level invite)."},"workspace_display_name":{"type":"string","description":"The workspace display name (not set if org-level invite)."},"roles":{"type":"array","items":{"type":"string"},"description":"List of role resource names included in this invitation."},"is_accepted":{"type":"boolean","description":"Whether the invitation has been accepted."},"redirect_organization_id":{"type":"string","description":"The organization ID to redirect to (set if invitation points to a different org)."},"redirect_workspace_id":{"type":"string","description":"The workspace ID to redirect to (set if invitation points to a different workspace)."}},"description":"An Invitation represents a pending invitation to join an organization or workspace."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/invitations/{invitation_id}":{"get":{"summary":"Get Invitation","operationId":"GetInvitation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Invitation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/invites > List Organization User Invites ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListOrganizationUserInvitesResponse":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/v1UserInvitation"},"description":"The list of pending user invitations."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListOrganizationUserInvites to get the next page of results."}},"description":"Response message for ListOrganizationUserInvites."},"v1UserInvitation":{"type":"object","properties":{"email":{"type":"string","description":"The user's email address."},"invitation_id":{"type":"string","description":"The invitation ID."}},"description":"A UserInvitation represents a pending invitation with user email and invitation ID."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/invites":{"get":{"summary":"List Organization User Invites","operationId":"ListOrganizationUserInvites","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListOrganizationUserInvitesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of invitations to return.\nIf unspecified, at most 50 invitations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous ListOrganizationUserInvites call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/roles > List Organization Roles ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListOrganizationRolesResponse":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1Role"},"description":"The list of roles in the organization."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListOrganizationRoles to get the next page of results."}},"description":"Response message for ListOrganizationRoles."},"v1Role":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the role.\nFormat: organizations/{organization}/roles/{role} (org-level)\nFormat: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)"},"title":{"type":"string","description":"Human-readable title of the role (e.g., \"Administrator\", \"Editor\")."},"description":{"type":"string","description":"Description of what this role grants."},"permissions":{"type":"array","items":{"type":"string"},"title":"List of permission strings this role grants.\nFormat: \"action:Resource\" (e.g., \"create:Automation\", \"read:Workspace\")","readOnly":true}},"description":"A Role represents a concrete, assignable role that can be assigned to users.\nRoles can be created from RoleTemplates or as standalone custom roles.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/roles":{"get":{"summary":"List Organization Roles","operationId":"ListOrganizationRoles","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListOrganizationRolesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of roles to return.\nIf unspecified, at most 50 roles will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous ListOrganizationRoles call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/users > List Organization Users ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListOrganizationUsersResponse":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/v1UserWithRoles"},"description":"The list of users in the organization with their roles."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`ListOrganizationUsers` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing users in an organization."},"v1UserWithRoles":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/v1UserBasicInfo"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1RoleBasicInfo"},"description":"The user's assigned roles.\nEach role includes its scope (organization or workspace)."}},"description":"A user with their assigned roles.\nThis type is reusable for both organization and workspace user listing APIs.\nThe RoleScope field in each role indicates whether the role is org-level or workspace-level."},"v1UserBasicInfo":{"type":"object","properties":{"name":{"type":"string","title":"The unique resource name of the user basic info.\nFormat: `organizations/{organization}/users/{user_basic_info}`"},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address."}},"description":"Contains basic information about a user.\nThis is a lightweight representation used when full user details are not needed."},"v1RoleBasicInfo":{"type":"object","properties":{"name":{"type":"string","description":"The role name (e.g., \"workspace-admin\", \"org-admin\", or custom role name)."},"role_scope":{"$ref":"#/components/schemas/v1RoleScope"}},"title":"Lightweight role information following the UserBasicInfo pattern.\nNote: RoleScope is imported from rbac.proto"},"v1RoleScope":{"type":"string","enum":["ROLE_SCOPE_UNSPECIFIED","ROLE_SCOPE_ORGANIZATION","ROLE_SCOPE_WORKSPACE"],"default":"ROLE_SCOPE_UNSPECIFIED","description":"Defines the scope at which a role can be applied.\n\n - ROLE_SCOPE_UNSPECIFIED: Unspecified role scope.\n - ROLE_SCOPE_ORGANIZATION: Role applies at the organization level.\n - ROLE_SCOPE_WORKSPACE: Role applies at the workspace level."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/users":{"get":{"summary":"List Organization Users","operationId":"ListOrganizationUsers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListOrganizationUsersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of users to return.\nIf unspecified, at most 50 users will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous `ListOrganizationUsers` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListOrganizationUsers` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nSupported filter fields:\n- `role`: Filter by role name (case-insensitive). Example: `role=\"Organization Admin\"`\n- `role_scope`: Filter by role scope. Values: \"organization\" or \"workspace\". Example: `role_scope=organization`\n- `search`: Search by user display name or email (partial match). Example: `search:\"john\"`","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: display_name, email, created_time, updated_time\nExample: \"display_name,created_time desc\"\nDefault ordering is by created_time descending if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/users/{user\_id} > Get User Basic Info ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Manage organizations, users, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UserBasicInfo":{"type":"object","properties":{"name":{"type":"string","title":"The unique resource name of the user basic info.\nFormat: `organizations/{organization}/users/{user_basic_info}`"},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address."}},"description":"Contains basic information about a user.\nThis is a lightweight representation used when full user details are not needed."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/users/{user_id}":{"get":{"summary":"Get User Basic Info","operationId":"GetUserBasicInfo","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UserBasicInfo"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"user_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Organizations"]}}}} ``` # Workspaces Manage workspaces, members, roles, invitations, and preferences. ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/preferences > Get Workspace Preferences ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1WorkspacePreferences":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the workspace preferences.\nFormat: `organizations/{organization}/workspaces/{workspace}/preferences`"},"support_team_access":{"type":"boolean","description":"Support team access to workspace for debugging issues."},"general":{"$ref":"#/components/schemas/v1GeneralPreferences"}},"description":"Represents workspace-specific settings or preferences."},"v1GeneralPreferences":{"type":"object","properties":{"time_zone":{"type":"string","description":"The time zone preference.\nShould be an IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\", \"UTC\")."},"time_format":{"$ref":"#/components/schemas/v1TimeFormat"},"date_format":{"$ref":"#/components/schemas/v1DateFormat"},"decimal_symbol":{"$ref":"#/components/schemas/v1DecimalSymbol"},"decimal_places":{"type":"integer","format":"int32","description":"The number of digits after decimal point."},"measurement_system":{"$ref":"#/components/schemas/v1MeasurementSystem"}},"description":"General preferences for display and formatting.\nUsed by both workspace and organization preferences."},"v1TimeFormat":{"type":"string","enum":["TIME_FORMAT_UNSPECIFIED","TIME_FORMAT_12_HOUR","TIME_FORMAT_24_HOUR"],"default":"TIME_FORMAT_UNSPECIFIED","description":"Supported time formats.\n\n - TIME_FORMAT_UNSPECIFIED: Unspecified time format.\n - TIME_FORMAT_12_HOUR: 12-hour format (1:00 PM).\n - TIME_FORMAT_24_HOUR: 24-hour format (13:00)."},"v1DateFormat":{"type":"string","enum":["DATE_FORMAT_UNSPECIFIED","DATE_FORMAT_DD_MM_YYYY_SLASH","DATE_FORMAT_MM_DD_YYYY_SLASH","DATE_FORMAT_YYYY_MM_DD_DASH","DATE_FORMAT_DD_MM_YYYY_DASH","DATE_FORMAT_MM_DD_YYYY_DASH","DATE_FORMAT_YYYY_MM_DD_SLASH","DATE_FORMAT_DD_MM_YYYY_DOT","DATE_FORMAT_MM_DD_YYYY_DOT","DATE_FORMAT_YYYY_MM_DD_DOT","DATE_FORMAT_DD_MMM_YYYY","DATE_FORMAT_MMM_DD_YYYY","DATE_FORMAT_DD_MMMM_YYYY","DATE_FORMAT_MMMM_DD_YYYY"],"default":"DATE_FORMAT_UNSPECIFIED","description":"Supported date formats.\n\n - DATE_FORMAT_UNSPECIFIED: Unspecified date format.\n - DATE_FORMAT_DD_MM_YYYY_SLASH: DD/MM/YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_SLASH: MM/DD/YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DASH: YYYY-MM-DD format (ISO 8601).\n - DATE_FORMAT_DD_MM_YYYY_DASH: DD-MM-YYYY format.\n - DATE_FORMAT_MM_DD_YYYY_DASH: MM-DD-YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_SLASH: YYYY/MM/DD format.\n - DATE_FORMAT_DD_MM_YYYY_DOT: DD.MM.YYYY format (European style).\n - DATE_FORMAT_MM_DD_YYYY_DOT: MM.DD.YYYY format.\n - DATE_FORMAT_YYYY_MM_DD_DOT: YYYY.MM.DD format.\n - DATE_FORMAT_DD_MMM_YYYY: DD MMM YYYY format (e.g., 15 Jan 2024).\n - DATE_FORMAT_MMM_DD_YYYY: MMM DD, YYYY format (e.g., Jan 15, 2024).\n - DATE_FORMAT_DD_MMMM_YYYY: DD MMMM YYYY format (e.g., 15 January 2024).\n - DATE_FORMAT_MMMM_DD_YYYY: MMMM DD, YYYY format (e.g., January 15, 2024)."},"v1DecimalSymbol":{"type":"string","enum":["DECIMAL_SYMBOL_UNSPECIFIED","DECIMAL_SYMBOL_PERIOD","DECIMAL_SYMBOL_COMMA"],"default":"DECIMAL_SYMBOL_UNSPECIFIED","description":"Supported decimal symbols.\n\n - DECIMAL_SYMBOL_UNSPECIFIED: Unspecified decimal symbol.\n - DECIMAL_SYMBOL_PERIOD: Period (.) as decimal separator.\n - DECIMAL_SYMBOL_COMMA: Comma (,) as decimal separator."},"v1MeasurementSystem":{"type":"string","enum":["MEASUREMENT_SYSTEM_UNSPECIFIED","MEASUREMENT_SYSTEM_METRIC","MEASUREMENT_SYSTEM_IMPERIAL"],"default":"MEASUREMENT_SYSTEM_UNSPECIFIED","description":"Supported measurement systems.\n\n - MEASUREMENT_SYSTEM_UNSPECIFIED: Unspecified measurement system.\n - MEASUREMENT_SYSTEM_METRIC: Metric system.\n - MEASUREMENT_SYSTEM_IMPERIAL: Imperial system."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/preferences":{"get":{"summary":"Get Workspace Preferences","operationId":"GetWorkspacePreferences","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1WorkspacePreferences"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/invites > List Workspace User Invites ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceUserInvitesResponse":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/v1UserInvitation"},"description":"The list of pending user invitations."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListWorkspaceUserInvites to get the next page of results."}},"description":"Response message for ListWorkspaceUserInvites."},"v1UserInvitation":{"type":"object","properties":{"email":{"type":"string","description":"The user's email address."},"invitation_id":{"type":"string","description":"The invitation ID."}},"description":"A UserInvitation represents a pending invitation with user email and invitation ID."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/invites":{"get":{"summary":"List Workspace User Invites","operationId":"ListWorkspaceUserInvites","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceUserInvitesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of invitations to return.\nIf unspecified, at most 50 invitations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous ListWorkspaceUserInvites call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/roles > List Workspace Roles ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceRolesResponse":{"type":"object","properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1Role"},"description":"The list of roles in the workspace."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the page_token field in the subsequent call to\nListWorkspaceRoles to get the next page of results."}},"description":"Response message for ListWorkspaceRoles."},"v1Role":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the role.\nFormat: organizations/{organization}/roles/{role} (org-level)\nFormat: organizations/{organization}/workspaces/{workspace}/roles/{role} (workspace-level)"},"title":{"type":"string","description":"Human-readable title of the role (e.g., \"Administrator\", \"Editor\")."},"description":{"type":"string","description":"Description of what this role grants."},"permissions":{"type":"array","items":{"type":"string"},"title":"List of permission strings this role grants.\nFormat: \"action:Resource\" (e.g., \"create:Automation\", \"read:Workspace\")","readOnly":true}},"description":"A Role represents a concrete, assignable role that can be assigned to users.\nRoles can be created from RoleTemplates or as standalone custom roles.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/roles":{"get":{"summary":"List Workspace Roles","operationId":"ListWorkspaceRoles","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceRolesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of roles to return.\nIf unspecified, at most 50 roles will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous ListWorkspaceRoles call.\nProvide this to retrieve the subsequent page.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/users > List Workspace Users ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspaceUsersResponse":{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/v1UserWithRoles"},"description":"The list of users in the workspace with their roles."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`ListWorkspaceUsers` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing users in a workspace."},"v1UserWithRoles":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/v1UserBasicInfo"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/v1RoleBasicInfo"},"description":"The user's assigned roles.\nEach role includes its scope (organization or workspace)."}},"description":"A user with their assigned roles.\nThis type is reusable for both organization and workspace user listing APIs.\nThe RoleScope field in each role indicates whether the role is org-level or workspace-level."},"v1UserBasicInfo":{"type":"object","properties":{"name":{"type":"string","title":"The unique resource name of the user basic info.\nFormat: `organizations/{organization}/users/{user_basic_info}`"},"display_name":{"type":"string","description":"The user's display name."},"email":{"type":"string","description":"The user's email address."}},"description":"Contains basic information about a user.\nThis is a lightweight representation used when full user details are not needed."},"v1RoleBasicInfo":{"type":"object","properties":{"name":{"type":"string","description":"The role name (e.g., \"workspace-admin\", \"org-admin\", or custom role name)."},"role_scope":{"$ref":"#/components/schemas/v1RoleScope"}},"title":"Lightweight role information following the UserBasicInfo pattern.\nNote: RoleScope is imported from rbac.proto"},"v1RoleScope":{"type":"string","enum":["ROLE_SCOPE_UNSPECIFIED","ROLE_SCOPE_ORGANIZATION","ROLE_SCOPE_WORKSPACE"],"default":"ROLE_SCOPE_UNSPECIFIED","description":"Defines the scope at which a role can be applied.\n\n - ROLE_SCOPE_UNSPECIFIED: Unspecified role scope.\n - ROLE_SCOPE_ORGANIZATION: Role applies at the organization level.\n - ROLE_SCOPE_WORKSPACE: Role applies at the workspace level."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/users":{"get":{"summary":"List Workspace Users","operationId":"ListWorkspaceUsers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspaceUsersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of users to return.\nIf unspecified, at most 50 users will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous `ListWorkspaceUsers` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListWorkspaceUsers` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nSupported filter fields:\n- `role`: Filter by role name (case-insensitive). Example: `role=\"Workspace Viewer\"`\n- `role_scope`: Filter by role scope. Values: \"organization\" or \"workspace\". Example: `role_scope=workspace`\n- `search`: Search by user display name or email (partial match). Example: `search:\"john\"`","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: display_name, email, created_time, updated_time\nExample: \"display_name,created_time desc\"\nDefault ordering is by created_time descending if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces:countUsers > Count Workspace Users ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountWorkspaceUsersResponse":{"type":"object","properties":{"workspace_user_counts":{"type":"object","additionalProperties":{"type":"integer","format":"int32"},"description":"A map of workspace IDs to their respective user counts.\nThe key is the workspace ID, and the value is the count of users in that workspace."}},"description":"Response message for counting users in specific workspaces."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"CountWorkspaceUsersBody":{"type":"object","properties":{"workspace_ids":{"type":"array","items":{"type":"string"},"title":"The list of workspace IDs to get user counts for.\nEach workspace_id should be the workspace identifier (not the full resource name).\nThe full workspace resource names will be constructed as:\norganizations/{organization}/workspaces/{workspace_id}"}},"description":"Request message for counting users in specific workspaces.","required":["workspace_ids"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces:countUsers":{"post":{"summary":"Count Workspace Users","operationId":"CountWorkspaceUsers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountWorkspaceUsersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountWorkspaceUsersBody"}}},"required":true},"tags":["Workspaces"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id} > Get Workspace ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Workspace":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the workspace.\nFormat: organizations/{organization}/workspaces/{workspace}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the workspace.\nThis corresponds to the `name` column in the database."},"workspace_icon":{"type":"string","description":"The workspace icon data.\nThis field contains the identifier of the workspace icon."},"workspace_icon_color":{"type":"string","description":"The color of the workspace icon."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was last updated.","readOnly":true},"creator_display_name":{"type":"string","description":"The display name of the user who created the workspace.","readOnly":true},"creator_email":{"type":"string","description":"The email address of the user who created the workspace.","readOnly":true}},"description":"A Workspace is a container for agents within an organization.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}":{"get":{"summary":"Get Workspace","operationId":"GetWorkspace","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Workspace"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces > List Workspaces ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListWorkspacesResponse":{"type":"object","properties":{"workspaces":{"type":"array","items":{"$ref":"#/components/schemas/v1Workspace"},"description":"The list of workspaces."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`ListWorkspaces` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing workspaces."},"v1Workspace":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the workspace.\nFormat: organizations/{organization}/workspaces/{workspace}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the workspace.\nThis corresponds to the `name` column in the database."},"workspace_icon":{"type":"string","description":"The workspace icon data.\nThis field contains the identifier of the workspace icon."},"workspace_icon_color":{"type":"string","description":"The color of the workspace icon."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was last updated.","readOnly":true},"creator_display_name":{"type":"string","description":"The display name of the user who created the workspace.","readOnly":true},"creator_email":{"type":"string","description":"The email address of the user who created the workspace.","readOnly":true}},"description":"A Workspace is a container for agents within an organization.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces":{"get":{"summary":"List Workspaces","operationId":"ListWorkspaces","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListWorkspacesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of workspaces to return.\nIf unspecified, at most 50 workspaces will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous `ListWorkspaces` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListWorkspaces` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional. A filter expression to constrain the workspaces returned.\nThe expression follows the syntax defined in AIP-160.\nSupported fields for filtering:\n - `title`: The display name of the workspace\n\nExamples:\n - `title = \"My Workspace\"` - exact match\n - `title : \"workspace\"` - contains match (case-insensitive)","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Optional comma-separated list of fields to order by, following AIP-132.\nSupported fields: title, create_time, update_time\nExample: \"title\", \"create_time desc\", \"update_time desc,title\"\nDefault ordering is by create_time descending if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` ## GET /api/v1/me/organizations/{organization\_id}/workspaces > Current User Organization Workspaces ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Workspaces","description":"Manage workspaces, members, roles, invitations, and preferences."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CurrentUserOrganizationWorkspacesResponse":{"type":"object","properties":{"user_workspaces":{"type":"array","items":{"$ref":"#/components/schemas/v1Workspace"},"description":"The list of workspaces the current user has access to in the organization."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to\n`CurrentUserOrganizationWorkspaces` to get the next page of results. If this field is\nempty, it means there are no more results."}},"description":"Response message for listing workspaces for the current user within a specific organization."},"v1Workspace":{"type":"object","properties":{"name":{"type":"string","description":"The resource name of the workspace.\nFormat: organizations/{organization}/workspaces/{workspace}\nThis field is assigned by the server at creation and is immutable thereafter.\nClients may include this field in Get/Update/Delete requests to identify the resource."},"title":{"type":"string","description":"The user-defined display name for the workspace.\nThis corresponds to the `name` column in the database."},"workspace_icon":{"type":"string","description":"The workspace icon data.\nThis field contains the identifier of the workspace icon."},"workspace_icon_color":{"type":"string","description":"The color of the workspace icon."},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the workspace was last updated.","readOnly":true},"creator_display_name":{"type":"string","description":"The display name of the user who created the workspace.","readOnly":true},"creator_email":{"type":"string","description":"The email address of the user who created the workspace.","readOnly":true}},"description":"A Workspace is a container for agents within an organization.","required":["title"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/me/organizations/{organization_id}/workspaces":{"get":{"summary":"Current User Organization Workspaces","operationId":"CurrentUserOrganizationWorkspaces","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CurrentUserOrganizationWorkspacesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of workspaces to return.\nIf unspecified, at most 50 workspaces will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token, received from a previous `CurrentUserOrganizationWorkspaces` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `CurrentUserOrganizationWorkspaces` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter string following AIP-160 filtering standards.\nExample: \"title='Development'\"","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Workspaces"]}}}} ``` # Automations Create and configure automations, revisions, schedules, triggers, and connections. ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id} > Get Automation ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}":{"get":{"summary":"Get Automation","operationId":"GetAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## Query Automation > This custom method allows explicit selection of which version stage to retrieve:\ > \- AUTOMATION\_STAGE\_DRAFT: Returns the latest draft version\ > \- AUTOMATION\_STAGE\_PUBLISHED: Returns the latest published version ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:query":{"get":{"summary":"Query Automation","description":"This custom method allows explicit selection of which version stage to retrieve:\n- AUTOMATION_STAGE_DRAFT: Returns the latest draft version\n- AUTOMATION_STAGE_PUBLISHED: Returns the latest published version","operationId":"QueryAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Automation"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stage","description":"The publication stage of the automation to retrieve.\nDetermines which version of the automation to return:\n- AUTOMATION_STAGE_DRAFT: Returns the latest draft version\n- AUTOMATION_STAGE_PUBLISHED: Returns the latest published version\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution.","in":"query","required":true,"schema":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED"}}],"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/revisions/{revision\_id} > Get Automation Revision ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationRevision":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation revision.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision}\nThe revision ID is the semantic version string (e.g., \"0.1\", \"1.0\", \"2.0\")."},"snapshot":{"$ref":"#/components/schemas/v1Automation"},"create_time":{"type":"string","format":"date-time","description":"Timestamp when this revision was created.","readOnly":true},"alternate_ids":{"type":"array","items":{"type":"string"},"description":"Other revision IDs that reference the same snapshot (e.g., \"latest\").\nPer AIP-162, this allows aliases for revisions.","readOnly":true}},"description":"AutomationRevision represents a historical revision (version) of an automation.\nRevisions are immutable snapshots created each time an automation is updated.\nPer AIP-162, this resource contains the complete state via a snapshot field."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions/{revision_id}":{"get":{"summary":"Get Automation Revision","operationId":"GetAutomationRevision","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationRevision"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/revisions > List Automation Revisions ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationRevisionsResponse":{"type":"object","properties":{"revisions":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationRevision"},"description":"The list of automation revisions for the current page.\nRevisions are ordered in reverse chronological order (newest first)."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"ListAutomationRevisionsResponse returns a page of automation revisions and pagination information."},"v1AutomationRevision":{"type":"object","properties":{"name":{"type":"string","description":"The name of the automation revision.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/revisions/{revision}\nThe revision ID is the semantic version string (e.g., \"0.1\", \"1.0\", \"2.0\")."},"snapshot":{"$ref":"#/components/schemas/v1Automation"},"create_time":{"type":"string","format":"date-time","description":"Timestamp when this revision was created.","readOnly":true},"alternate_ids":{"type":"array","items":{"type":"string"},"description":"Other revision IDs that reference the same snapshot (e.g., \"latest\").\nPer AIP-162, this allows aliases for revisions.","readOnly":true}},"description":"AutomationRevision represents a historical revision (version) of an automation.\nRevisions are immutable snapshots created each time an automation is updated.\nPer AIP-162, this resource contains the complete state via a snapshot field."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/revisions":{"get":{"summary":"List Automation Revisions","operationId":"ListAutomationRevisions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationRevisionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of revisions to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, at most 50 revisions will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomationRevisions` call.\nProvide this to retrieve the subsequent page of results.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n - `stage`: The automation revision stage (e.g., DRAFT, PUBLISHED)\n\nExample filters:\n - `stage = \"DRAFT\"` - Returns only draft revisions\n - `stage = \"PUBLISHED\"` - Returns only published revisions\n\nIf not specified or passed null, all revisions will be returned for that automation.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations > List Automations ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationsResponse":{"type":"object","properties":{"automations":{"type":"array","items":{"$ref":"#/components/schemas/v1Automation"},"description":"The list of automations for the current page.\nMay be empty if no automations match the request criteria."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"ListAutomationsResponse returns a page of automations and pagination information."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations":{"get":{"summary":"List Automations","operationId":"ListAutomations","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of automations to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, at most 10 automations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nIf negative, an INVALID_ARGUMENT error will be returned.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomations` call.\nProvide this to retrieve the subsequent page of results.\nWhen paginating, all other parameters provided to `ListAutomations` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"show_deleted","description":"Filter to show/hide deleted automations. Deleted automations will be hidden by default.","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n - `state`: The automation state (e.g., DRAFT, PUBLISHED)\n\nExample filters:\n - `state = \"PUBLISHED\"`","in":"query","required":false,"schema":{"type":"string"}},{"name":"order_by","description":"Reserved for future use. Comma-separated list of fields to order results by.\nPer AIP-132, this should be a string containing one or more field names,\neach optionally followed by \"asc\" or \"desc\" to specify sort direction.\n\nCurrently not implemented. Results are always ordered by `update_time desc`\n(most recently updated first).","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:invoke > Invoke Automation ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1InvokeAutomationResponse":{"type":"object","properties":{"run_id":{"type":"string","description":"Unique identifier of the run created to execute the automation.\nUse this ID to track execution status and retrieve results."}},"description":"InvokeAutomationResponse returns the run ID for tracking the automation execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"InvokeAutomationBody":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input values to pass to the automation execution.\nKeys are input parameter names, values are the corresponding values."},"stage":{"$ref":"#/components/schemas/v1AutomationStage"}},"description":"InvokeAutomationRequest contains the automation ID and inputs needed to execute an automation.","required":["stage"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:invoke":{"post":{"summary":"Invoke Automation","operationId":"InvokeAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1InvokeAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeAutomationBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## List Default Inputs History > Results are returned in reverse chronological order (newest first).\ > Optionally filter by stage (DRAFT or PUBLISHED). ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListDefaultInputsHistoryResponse":{"type":"object","properties":{"default_inputs_history_entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DefaultInputsHistoryEntry"},"description":"The history entries, ordered newest first."},"next_page_token":{"type":"string","description":"Token for retrieving the next page. Empty if no more results."}},"description":"ListDefaultInputsHistoryResponse contains a paginated list of default input history entries."},"v1DefaultInputsHistoryEntry":{"type":"object","properties":{"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The default inputs snapshot at the time of this change.","readOnly":true},"change_time":{"type":"string","format":"date-time","description":"When this change was made.","readOnly":true},"change_actor":{"type":"string","description":"User ID of the person who made this change.","readOnly":true}},"description":"DefaultInputsHistoryEntry represents a single default input change event."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:listDefaultInputsHistory":{"get":{"summary":"List Default Inputs History","description":"Results are returned in reverse chronological order (newest first).\nOptionally filter by stage (DRAFT or PUBLISHED).","operationId":"ListDefaultInputsHistory","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListDefaultInputsHistoryResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"Maximum number of entries to return. Defaults to 50 if not specified.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Page token for pagination, from a previous ListDefaultInputsHistoryResponse.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations:countConnectionUsage > Count Connection Usage ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountConnectionUsageResponse":{"type":"object","properties":{"connection_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionAutomationCount"},"description":"List of connection IDs with their corresponding automation counts.\nThe order matches the order of connection_ids in the request."}},"description":"CountConnectionUsageResponse returns automation counts for each requested connection ID."},"v1ConnectionAutomationCount":{"type":"object","properties":{"connection_id":{"type":"string","description":"The connection ID being counted."},"count":{"type":"integer","format":"int32","description":"The number of automations that use this connection.\nIncludes both DRAFT and PUBLISHED automations by default."}},"description":"ConnectionAutomationCount represents the count of automations using a specific connection."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"CountConnectionUsageBody":{"type":"object","properties":{"connection_ids":{"type":"array","items":{"type":"string"},"description":"List of connection IDs to count automation usage for.\nEach connection ID will have a corresponding entry in the response."}},"description":"CountConnectionUsageRequest specifies connection IDs to count automation usage for.","required":["connection_ids"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:countConnectionUsage":{"post":{"summary":"Count Connection Usage","operationId":"CountConnectionUsage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountConnectionUsageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountConnectionUsageBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations:traceConnectionUsage > Trace Connection Usage ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1TraceConnectionUsageResponse":{"type":"object","properties":{"automations":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationConnectionUsage"},"description":"List of automations that use the specified connection, with their stages."}},"description":"TraceConnectionUsageResponse returns automations that use the specified connection."},"v1AutomationConnectionUsage":{"type":"object","properties":{"automation_id":{"type":"string","description":"The automation ID that uses the connection.\nThis is the automation ID portion only (e.g., the {automation} part of the resource name)."},"stages":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationStage"},"description":"The stages in which this automation uses the connection.\nCan include AUTOMATION_STAGE_DRAFT, AUTOMATION_STAGE_PUBLISHED, or both."}},"description":"AutomationConnectionUsage represents an automation that uses a specific connection,\nalong with the stages (DRAFT, PUBLISHED, or both) where the connection is used."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"TraceConnectionUsageBody":{"type":"object","properties":{"connection_id":{"type":"string","description":"The connection ID to trace usage for.\nReturns all automations that use this connection."}},"description":"TraceConnectionUsageRequest specifies which connection to trace usage for.","required":["connection_id"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:traceConnectionUsage":{"post":{"summary":"Trace Connection Usage","operationId":"TraceConnectionUsage","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1TraceConnectionUsageResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TraceConnectionUsageBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:extractCodeConnections > Extract Automation Code Connections ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ExtractAutomationCodeConnectionsResponse":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"List of connections found in the automation's SPy code.\nIncludes both placeholder connections (without connection_id) and concrete connections (with connection_id).","readOnly":true}},"description":"ExtractAutomationCodeConnectionsResponse returns connection information from the automation's SPy code."},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:extractCodeConnections":{"get":{"summary":"Extract Automation Code Connections","operationId":"ExtractAutomationCodeConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ExtractAutomationCodeConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression to restrict results. Per AIP-160, this should be a\nfiltering expression following the Common Expression Language (CEL) syntax.\n\nSupported fields for filtering:\n - `stage`: The automation stage to extract connections from (e.g., DRAFT, PUBLISHED)\n\nExample filters:\n - `stage = \"DRAFT\"`\n - `stage = \"PUBLISHED\"`","in":"query","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## Upgrade Automation Connections > Multiple connections can be upgraded in a single atomic operation. All upgrades succeed\ > together or all fail together. The automation version is incremented once for all upgrades.\ > \ > This operation only works on draft automations. To upgrade connections in a published\ > automation, first use ForkPublishedAutomation to create a draft, then call this method.\ > \ > Per AIP-136, this is a custom method using the :upgradeConnections suffix. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UpgradeAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"UpgradeAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"UpgradeAutomationConnectionsBody":{"type":"object","properties":{"upgrades":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionReplacement"},"description":"List of connections to upgrade. All upgrades are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all upgrades.\n\nEach old_connection_id must be unique within the list. If the same old_connection_id\nappears multiple times, the request will fail with INVALID_ARGUMENT."}},"description":"UpgradeAutomationConnectionsRequest specifies which connections to upgrade in a draft automation.","required":["upgrades"]},"v1ConnectionReplacement":{"type":"object","properties":{"old_connection_id":{"type":"string","description":"The current connection ID to replace.\nThis connection ID must exist in the automation."},"new_connection_id":{"type":"string","title":"The new connection ID to use as replacement.\nThis connection must:\n- Exist in the workspace\n- Have the same book_name as the old connection\n- Have the same book_version as the old connection"},"connection_alias":{"type":"string","description":"The alias of the connection to use as replacement.\nThis alias must be unique within the automation."}},"description":"ConnectionReplacement specifies replacing one connection ID with another.","required":["old_connection_id","new_connection_id","connection_alias"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:upgradeConnections":{"post":{"summary":"Upgrade Automation Connections","description":"Multiple connections can be upgraded in a single atomic operation. All upgrades succeed\ntogether or all fail together. The automation version is incremented once for all upgrades.\n\nThis operation only works on draft automations. To upgrade connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :upgradeConnections suffix.","operationId":"UpgradeAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UpgradeAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## Switch Automation Connections > Multiple connections can be switched in a single atomic operation. All switches succeed\ > together or all fail together. The automation version is incremented once for all switches.\ > \ > This operation only works on draft automations. To switch connections in a published\ > automation, first use ForkPublishedAutomation to create a draft, then call this method.\ > \ > Per AIP-136, this is a custom method using the :switchConnections suffix. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1SwitchAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"SwitchAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SwitchAutomationConnectionsBody":{"type":"object","properties":{"switches":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionReplacement"},"description":"List of connections to switch. All switches are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all switches.\n\nEach old_connection_id must be unique within the list. If the same old_connection_id\nappears multiple times, the request will fail with INVALID_ARGUMENT."}},"description":"SwitchAutomationConnectionsRequest specifies which connections to switch in a draft automation.","required":["switches"]},"v1ConnectionReplacement":{"type":"object","properties":{"old_connection_id":{"type":"string","description":"The current connection ID to replace.\nThis connection ID must exist in the automation."},"new_connection_id":{"type":"string","title":"The new connection ID to use as replacement.\nThis connection must:\n- Exist in the workspace\n- Have the same book_name as the old connection\n- Have the same book_version as the old connection"},"connection_alias":{"type":"string","description":"The alias of the connection to use as replacement.\nThis alias must be unique within the automation."}},"description":"ConnectionReplacement specifies replacing one connection ID with another.","required":["old_connection_id","new_connection_id","connection_alias"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:switchConnections":{"post":{"summary":"Switch Automation Connections","description":"Multiple connections can be switched in a single atomic operation. All switches succeed\ntogether or all fail together. The automation version is incremented once for all switches.\n\nThis operation only works on draft automations. To switch connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :switchConnections suffix.","operationId":"SwitchAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1SwitchAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwitchAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## Remove Automation Connections > Multiple connections can be removed in a single atomic operation. All removals succeed\ > together or all fail together. The automation version is incremented once for all removals.\ > \ > This operation only works on draft automations. To remove connections in a published\ > automation, first use ForkPublishedAutomation to create a draft, then call this method.\ > \ > Per AIP-136, this is a custom method using the :removeConnections suffix. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1RemoveAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"RemoveAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"RemoveAutomationConnectionsBody":{"type":"object","properties":{"removals":{"type":"array","items":{"$ref":"#/components/schemas/v1ConnectionRemoval"},"description":"List of connections to remove. All removals are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all removals.\n\nEach connection (identified by connection_id and connection_alias) must be unique\nwithin the list. If the same connection appears multiple times, the request will\nfail with INVALID_ARGUMENT.\n\nFor each connection, the corresponding entry in automation.connections will be removed\nand code references will be replaced with placeholders (kognitos.connection_name.{book})."}},"description":"RemoveAutomationConnectionsRequest specifies which connections to remove from a draft automation.","required":["removals"]},"v1ConnectionRemoval":{"type":"object","properties":{"connection_id":{"type":"string","description":"The connection ID to remove.\nThis connection ID must exist in the automation."},"connection_alias":{"type":"string","description":"The alias of the connection to remove.\nThis alias must match the connection being removed."}},"description":"ConnectionRemoval specifies a connection to remove from an automation.","required":["connection_id","connection_alias"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:removeConnections":{"post":{"summary":"Remove Automation Connections","description":"Multiple connections can be removed in a single atomic operation. All removals succeed\ntogether or all fail together. The automation version is incremented once for all removals.\n\nThis operation only works on draft automations. To remove connections in a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :removeConnections suffix.","operationId":"RemoveAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1RemoveAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## Add Automation Connections > Multiple connections can be added in a single atomic operation. All additions succeed\ > together or all fail together. The automation version is incremented once for all additions.\ > \ > This operation only works on draft automations. To add connections to a published\ > automation, first use ForkPublishedAutomation to create a draft, then call this method.\ > \ > Per AIP-136, this is a custom method using the :addConnections suffix. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AddAutomationConnectionsResponse":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/v1Automation"}},"description":"AddAutomationConnectionsResponse returns the updated automation."},"v1Automation":{"type":"object","properties":{"name":{"type":"string","title":"The automation name (e.g. 'automations/{automation}')"},"display_name":{"type":"string","description":"Human-readable name of the automation for identification and display.\nMust be unique within the user's namespace."},"english_code":{"type":"string","description":"User-facing English description code that explains what the automation does.\nThis is a human-readable representation of the automation's purpose and logic."},"code":{"type":"string","description":"SPy (Subset-of Python) executable code that defines the automation logic.\nThis code is executed when the automation is invoked with inputs."},"artifacts":{"type":"object","additionalProperties":{"type":"string","format":"byte"},"description":"Additional artifacts associated with the automation (e.g., data files, configurations).\nKeys are artifact names, values are the binary content of the artifacts.\nThese artifacts are available to the automation during execution."},"create_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was originally created.\nThis value never changes after creation.","readOnly":true},"version":{"type":"string","title":"Semantic version of this specific version of the automation (format: major.minor).\nIncremented each time the automation is updated or published.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this automation for execution.\nMaps connection names to their metadata.\nThese connections are resolved and made available during automation execution."},"update_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last updated.\nUpdated whenever the automation metadata, code, or dependencies change.","readOnly":true},"update_user_id":{"type":"string","description":"The ID of the user who last updated this automation.","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was deleted.","readOnly":true},"purge_time":{"type":"string","format":"date-time","description":"Timestamp when the automation will be purged.","readOnly":true},"input_specs":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationInputSpec"},"description":"List of input specifications that define the parameters this automation accepts.\nThese specifications describe the expected inputs when the automation is executed."},"description":{"type":"string","description":"Provides additional context and documentation about the automation's purpose and behavior."},"latest_published_version":{"type":"string","title":"Semantic version of the latest published version of the automation (format: major.minor).\nIt will be null in case of no published version.\nExamples: \"0.1\", \"1.0\", \"2.0\"","readOnly":true},"author_id":{"type":"string","description":"The ID of the user who created this automation.","readOnly":true},"code_mapping":{"$ref":"#/components/schemas/v1CodeMapping"},"restore_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was restored from a previous version.\nOnly populated if the automation has been restored.","readOnly":true},"restore_version":{"type":"string","description":"The version string this automation was restored from (e.g., \"1.0\", \"2.1\").\nOnly populated if the automation has been restored.","readOnly":true},"restore_user_id":{"type":"string","description":"The ID of the user who restored this automation.\nOnly populated if the automation has been restored.","readOnly":true},"publish_time":{"type":"string","format":"date-time","description":"Timestamp when the automation was last published.\nOnly populated if the automation has been published.","readOnly":true},"publish_user_id":{"type":"string","description":"The ID of the user who last published this automation.\nOnly populated if the automation has been published.","readOnly":true},"activation_state":{"$ref":"#/components/schemas/v1AutomationActivationState"},"default_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Default input values for this automation.\nKeys are input parameter names (matching AutomationInputSpec.name),\nvalues are the default values to use when inputs are not explicitly provided.\nThese are used to pre-populate inputs for manual runs and fill missing inputs\nfor trigger-based invocations.","readOnly":true},"marked_outputs":{"type":"array","items":{"type":"string"},"description":"List of output keys that have been marked by the user.\nThese keys identify specific outputs from the automation execution."}},"description":"Automation represents a unit of executable code with associated metadata and dependencies.\nAutomations can be in DRAFT or PUBLISHED state, where drafts can be modified and\npublished automations are immutable and executable.\nAutomation IDs are unique nano ID strings (21 characters, URL-safe: A-Za-z0-9_-).","required":["display_name"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationInputSpec":{"type":"object","properties":{"name":{"type":"string","description":"The name of the input parameter."},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"AutomationInputSpec defines the specification for an input parameter of an automation.","required":["name"]},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"v1CodeMapping":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1CodeMappingEntry"},"description":"List of mapping entries that associate SPy code regions with English code regions.\nEach entry defines a paired relationship between a span in the SPy code and\na span in the English code representation."}},"description":"CodeMapping represents a bidirectional mapping between SPy (Subset-of-Python) code\nand English code locations within an automation. This mapping enables navigation between\nthe two representations, facilitating debugging, traceability, and synchronized editing.\nEach entry in the mapping associates a region in the SPy code with its corresponding\nregion in the English code. The mapping relationship is many-to-many and entries may\noverlap.","required":["entries"]},"v1CodeMappingEntry":{"type":"object","properties":{"spy_location":{"$ref":"#/components/schemas/commonV1Location"},"english_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"CodeMappingEntry represents a single mapping between a region in SPy code and\nits corresponding region in English code. This bidirectional association allows\nnavigation from SPy to English and vice versa, enabling synchronized views and\ndebugging across both representations of the automation logic.","required":["spy_location","english_location"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1AutomationActivationState":{"type":"string","enum":["AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","AUTOMATION_ACTIVATION_STATE_ACTIVE","AUTOMATION_ACTIVATION_STATE_DEACTIVATED"],"default":"AUTOMATION_ACTIVATION_STATE_UNSPECIFIED","description":"Activation state of a published automation.\nControls whether the automation can execute published runs.\n\n - AUTOMATION_ACTIVATION_STATE_UNSPECIFIED: Unspecified state. Used when automation has no published version.\nActivation state is only meaningful after publishing.\n - AUTOMATION_ACTIVATION_STATE_ACTIVE: Automation is active and can execute published runs.\n - AUTOMATION_ACTIVATION_STATE_DEACTIVATED: Automation is deactivated and cannot execute published runs.\nEvents will be logged but not executed."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AddAutomationConnectionsBody":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/v1CredentialInfo"},"description":"List of connections to add. All additions are performed atomically:\neither all succeed or all fail. The automation version is incremented once\nfor all additions.\n\nEach connection must be unique within the list. If duplicate connections appear,\nthe request will fail with INVALID_ARGUMENT."}},"description":"AddAutomationConnectionsRequest specifies which connections to add to a draft automation.","required":["connections"]},"v1CredentialInfo":{"type":"object","properties":{"book":{"type":"string","description":"The name of the book requiring credentials.\nThis field represents the book name."},"book_version":{"type":"string","description":"The version of the book."},"connection_alias":{"type":"string","description":"The alias of the connection within the automation.\nThis field represents the connection alias."},"connection_id":{"type":"string","description":"The unique identifier of the connection."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"}},"description":"CredentialInfo describes connection credential information.","required":["book","book_version"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:addConnections":{"post":{"summary":"Add Automation Connections","description":"Multiple connections can be added in a single atomic operation. All additions succeed\ntogether or all fail together. The automation version is incremented once for all additions.\n\nThis operation only works on draft automations. To add connections to a published\nautomation, first use ForkPublishedAutomation to create a draft, then call this method.\n\nPer AIP-136, this is a custom method using the :addConnections suffix.","operationId":"AddAutomationConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AddAutomationConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAutomationConnectionsBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/visualization > Get Automation Visualization ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationVisualization":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the visualization.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/visualization"},"graph":{"$ref":"#/components/schemas/v1FlowGraph"},"automation_version":{"type":"string","description":"The semantic version of the automation this visualization represents.\nFormat: \"major.0\" (e.g., \"1.0\", \"2.0\", \"3.0\") - always a published version.\nThis corresponds to the automation's published version at the time of generation.","readOnly":true},"state":{"$ref":"#/components/schemas/v1VisualizationState"},"error_message":{"type":"string","description":"Error message describing why generation failed.\nOnly populated when state is VISUALIZATION_STATE_FAILED.","readOnly":true}},"description":"AutomationVisualization represents a visual representation of an automation's execution flow.\nVisualizations are generated for published automation versions and stored as configurations\nfor rendering in the UI. This is a singleton resource - each automation has exactly one visualization\nrepresenting its latest published version."},"v1FlowGraph":{"type":"object","properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/v1FlowNode"},"description":"List of nodes representing steps in the automation flow."},"edges":{"type":"array","items":{"$ref":"#/components/schemas/v1FlowEdge"},"description":"List of edges representing connections between nodes."}},"description":"FlowGraph represents the execution flow of an automation as a directed graph.\nThe graph consists of nodes (representing steps) and edges (representing transitions)."},"v1FlowNode":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this node within the graph."},"label":{"type":"string","description":"Human-readable label describing this step."},"type":{"$ref":"#/components/schemas/v1FlowNodeType"}},"description":"FlowNode represents a single step or decision point in the automation flow."},"v1FlowNodeType":{"type":"string","enum":["FLOW_NODE_TYPE_UNSPECIFIED","FLOW_NODE_TYPE_START","FLOW_NODE_TYPE_END","FLOW_NODE_TYPE_PROCESS","FLOW_NODE_TYPE_DECISION","FLOW_NODE_TYPE_INPUT","FLOW_NODE_TYPE_OUTPUT"],"default":"FLOW_NODE_TYPE_UNSPECIFIED","description":"FlowNodeType defines the different types of nodes in an automation flow.\n\n - FLOW_NODE_TYPE_UNSPECIFIED: Unspecified node type.\n - FLOW_NODE_TYPE_START: Start node - represents the beginning of the flow.\n - FLOW_NODE_TYPE_END: End node - represents the end of the flow.\n - FLOW_NODE_TYPE_PROCESS: Process node - represents a processing step.\n - FLOW_NODE_TYPE_DECISION: Decision node - represents a branching point (if-else conditions).\n - FLOW_NODE_TYPE_INPUT: Input node - represents an input action.\n - FLOW_NODE_TYPE_OUTPUT: Output node - represents an output action."},"v1FlowEdge":{"type":"object","properties":{"source":{"type":"string","description":"ID of the source node where the edge originates."},"target":{"type":"string","description":"ID of the target node where the edge points."},"condition":{"type":"string","description":"Optional condition label for the edge (e.g., \"Yes\", \"No\" for decision branches)."}},"description":"FlowEdge represents a directed connection between two nodes."},"v1VisualizationState":{"type":"string","enum":["VISUALIZATION_STATE_UNSPECIFIED","VISUALIZATION_STATE_PENDING","VISUALIZATION_STATE_COMPLETED","VISUALIZATION_STATE_FAILED"],"default":"VISUALIZATION_STATE_UNSPECIFIED","description":"VisualizationState indicates the current state of visualization generation.\n\n - VISUALIZATION_STATE_UNSPECIFIED: Unspecified state.\n - VISUALIZATION_STATE_PENDING: Visualization generation is in progress.\n - VISUALIZATION_STATE_COMPLETED: Visualization generation completed successfully.\n - VISUALIZATION_STATE_FAILED: Visualization generation failed."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/visualization":{"get":{"summary":"Get Automation Visualization","operationId":"GetAutomationVisualization","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationVisualization"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule > Get Automation Schedule ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."}},"description":"Time window for querying insights.","required":["start_time","end_time"]},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"get":{"summary":"Get Automation Schedule","operationId":"GetAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule > Create Automation Schedule ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."}},"description":"Time window for querying insights.","required":["start_time","end_time"]},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"post":{"summary":"Create Automation Schedule","operationId":"CreateAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}},"description":"The schedule to create.","required":true},"tags":["Automations"]}}}} ``` ## DELETE /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule > Delete Automation Schedule ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"delete":{"summary":"Delete Automation Schedule","operationId":"DeleteAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## PATCH /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/schedule > Update Automation Schedule ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."}},"description":"Time window for querying insights.","required":["start_time","end_time"]},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/schedule":{"patch":{"summary":"Update Automation Schedule","operationId":"UpdateAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationSchedule"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"title":"The schedule to update.","required":["config"]}}},"description":"The schedule to update.","required":true},"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:disableAutomationSchedule > Disable Automation Schedule ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DisableAutomationScheduleResponse":{"type":"object","properties":{"schedule":{"$ref":"#/components/schemas/v1AutomationSchedule"}},"description":"DisableAutomationScheduleResponse contains the disabled schedule."},"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."}},"description":"Time window for querying insights.","required":["start_time","end_time"]},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"DisableAutomationScheduleBody":{"type":"object","description":"DisableAutomationScheduleRequest is the request to disable a schedule (pause without deleting)."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:disableAutomationSchedule":{"post":{"summary":"Disable Automation Schedule","operationId":"DisableAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DisableAutomationScheduleResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisableAutomationScheduleBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}:enableAutomationSchedule > Enable Automation Schedule ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1EnableAutomationScheduleResponse":{"type":"object","properties":{"schedule":{"$ref":"#/components/schemas/v1AutomationSchedule"}},"description":"EnableAutomationScheduleResponse contains the enabled schedule."},"v1AutomationSchedule":{"type":"object","properties":{"name":{"type":"string","title":"Resource name of the schedule.\nFormat: organizations/{org}/workspaces/{ws}/automations/{automation}/schedule"},"config":{"$ref":"#/components/schemas/v1ScheduleConfig"},"enabled":{"type":"boolean","description":"Whether the schedule is currently enabled.\nDisabled schedules do not trigger automation invocations.","readOnly":true},"summary":{"type":"string","title":"Human-readable summary of the schedule for display in the UI.\nGenerated by the backend based on the schedule configuration.\nExamples: \"Every weekday at 9:00 AM PT\", \"Monthly on the 4th Friday at 2:30 PM\"","readOnly":true},"next_run_times":{"type":"array","items":{"type":"string","format":"date-time"},"description":"List of the next scheduled execution times.\nUseful for preview and verification. Backend generates these.","readOnly":true},"remaining_occurrences":{"type":"integer","format":"int32","description":"Number of remaining occurrences if the schedule has an end condition.\nOnly populated when config.end.end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.","readOnly":true}},"description":"AutomationSchedule represents a schedule for invoking an automation.\nEach automation can have at most one schedule. Kestra is the source of truth.","required":["config"]},"v1ScheduleConfig":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/v1ScheduleStart"},"repeat_interval":{"$ref":"#/components/schemas/v1RepeatInterval"},"weekly_pattern":{"$ref":"#/components/schemas/v1DayOfWeekPattern"},"monthly_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"},"yearly_pattern":{"$ref":"#/components/schemas/v1MonthPattern"},"active_window":{"$ref":"#/components/schemas/v1TimeWindow"},"end":{"$ref":"#/components/schemas/v1ScheduleEnd"}},"description":"ScheduleConfig is the main user-friendly configuration for automation schedules.\nThe backend generates the appropriate scheduling logic from this configuration.","required":["start"]},"v1ScheduleStart":{"type":"object","properties":{"start_date":{"$ref":"#/components/schemas/typeDate"},"time":{"$ref":"#/components/schemas/typeTimeOfDay"},"time_zone":{"type":"string","description":"Timezone for the schedule. Defaults to \"UTC\" if not specified.\nUse IANA timezone identifiers (e.g., \"America/New_York\", \"America/Los_Angeles\", \"Europe/London\")."}},"description":"ScheduleStart defines when the schedule begins."},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"v1RepeatInterval":{"type":"object","properties":{"unit":{"$ref":"#/components/schemas/v1FrequencyUnit"},"interval":{"type":"integer","format":"int32","description":"The interval value. For example, 2 with FREQUENCY_UNIT_WEEK means \"every 2 weeks\".\nMust be a positive integer. Defaults to 1 if not specified."}},"description":"RepeatInterval defines how often the schedule repeats.","required":["unit"]},"v1FrequencyUnit":{"type":"string","enum":["FREQUENCY_UNIT_UNSPECIFIED","FREQUENCY_UNIT_MINUTE","FREQUENCY_UNIT_HOUR","FREQUENCY_UNIT_DAY","FREQUENCY_UNIT_WEEK","FREQUENCY_UNIT_MONTH","FREQUENCY_UNIT_YEAR"],"default":"FREQUENCY_UNIT_UNSPECIFIED","description":"FrequencyUnit defines the unit for schedule repetition.\n\n - FREQUENCY_UNIT_UNSPECIFIED: Unspecified frequency unit.\n - FREQUENCY_UNIT_MINUTE: Schedule repeats every N minutes.\n - FREQUENCY_UNIT_HOUR: Schedule repeats every N hours.\n - FREQUENCY_UNIT_DAY: Schedule repeats every N days.\n - FREQUENCY_UNIT_WEEK: Schedule repeats every N weeks.\n - FREQUENCY_UNIT_MONTH: Schedule repeats every N months.\n - FREQUENCY_UNIT_YEAR: Schedule repeats every N years."},"v1DayOfWeekPattern":{"type":"object","properties":{"days":{"type":"array","items":{"$ref":"#/components/schemas/v1DayOfWeek"},"description":"Days of the week when the schedule should run.\nAt least one day must be specified."}},"description":"DayOfWeekPattern specifies which days of the week to run.\nUsed for weekly schedules (e.g., \"every Monday\", \"every Mon/Wed/Fri\").","required":["days"]},"v1DayOfWeek":{"type":"string","enum":["DAY_OF_WEEK_UNSPECIFIED","DAY_OF_WEEK_MONDAY","DAY_OF_WEEK_TUESDAY","DAY_OF_WEEK_WEDNESDAY","DAY_OF_WEEK_THURSDAY","DAY_OF_WEEK_FRIDAY","DAY_OF_WEEK_SATURDAY","DAY_OF_WEEK_SUNDAY"],"default":"DAY_OF_WEEK_UNSPECIFIED","description":"DayOfWeek represents days of the week for scheduling.\nValues align with ISO 8601 (Monday = 1, Sunday = 7).\n\n - DAY_OF_WEEK_UNSPECIFIED: Unspecified day.\n - DAY_OF_WEEK_MONDAY: Monday.\n - DAY_OF_WEEK_TUESDAY: Tuesday.\n - DAY_OF_WEEK_WEDNESDAY: Wednesday.\n - DAY_OF_WEEK_THURSDAY: Thursday.\n - DAY_OF_WEEK_FRIDAY: Friday.\n - DAY_OF_WEEK_SATURDAY: Saturday.\n - DAY_OF_WEEK_SUNDAY: Sunday."},"v1DayOfMonthPattern":{"type":"object","properties":{"day_number":{"type":"integer","format":"int32","description":"Run on a specific day of the month (1-31).\nIf the month has fewer days, runs on the last day of that month."},"ordinal_day":{"$ref":"#/components/schemas/v1OrdinalDayOfWeek"}},"description":"DayOfMonthPattern specifies which day(s) of the month to run.\nUsed for monthly schedules."},"v1OrdinalDayOfWeek":{"type":"object","properties":{"ordinal":{"$ref":"#/components/schemas/v1Ordinal"},"day":{"$ref":"#/components/schemas/v1DayOfWeek"}},"description":"OrdinalDayOfWeek represents a pattern like \"first Monday\" or \"last Friday\".\nUsed as a building block for monthly and yearly patterns.","required":["ordinal","day"]},"v1Ordinal":{"type":"string","enum":["ORDINAL_UNSPECIFIED","ORDINAL_FIRST","ORDINAL_SECOND","ORDINAL_THIRD","ORDINAL_FOURTH","ORDINAL_FIFTH","ORDINAL_LAST"],"default":"ORDINAL_UNSPECIFIED","description":"Ordinal represents the position within a period (e.g., \"first Monday of month\").\n\n - ORDINAL_UNSPECIFIED: Unspecified ordinal.\n - ORDINAL_FIRST: First occurrence (e.g., first Monday).\n - ORDINAL_SECOND: Second occurrence.\n - ORDINAL_THIRD: Third occurrence.\n - ORDINAL_FOURTH: Fourth occurrence.\n - ORDINAL_FIFTH: Fifth occurrence (not all months have a fifth occurrence of each day).\n - ORDINAL_LAST: Last occurrence (e.g., last Friday of month)."},"v1MonthPattern":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/v1Month"},"day_pattern":{"$ref":"#/components/schemas/v1DayOfMonthPattern"}},"description":"MonthPattern specifies which month and day to run.\nUsed for yearly schedules (e.g., \"July 30\", \"last Friday of December\").","required":["month","day_pattern"]},"v1Month":{"type":"string","enum":["MONTH_UNSPECIFIED","MONTH_JANUARY","MONTH_FEBRUARY","MONTH_MARCH","MONTH_APRIL","MONTH_MAY","MONTH_JUNE","MONTH_JULY","MONTH_AUGUST","MONTH_SEPTEMBER","MONTH_OCTOBER","MONTH_NOVEMBER","MONTH_DECEMBER"],"default":"MONTH_UNSPECIFIED","description":"Month represents months of the year.\n\n - MONTH_UNSPECIFIED: Unspecified month.\n - MONTH_JANUARY: January.\n - MONTH_FEBRUARY: February.\n - MONTH_MARCH: March.\n - MONTH_APRIL: April.\n - MONTH_MAY: May.\n - MONTH_JUNE: June.\n - MONTH_JULY: July.\n - MONTH_AUGUST: August.\n - MONTH_SEPTEMBER: September.\n - MONTH_OCTOBER: October.\n - MONTH_NOVEMBER: November.\n - MONTH_DECEMBER: December."},"v1TimeWindow":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time of the window (inclusive)."},"end_time":{"type":"string","format":"date-time","description":"The end time of the window (inclusive)."},"time_zone":{"type":"string","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified."}},"description":"Time window for querying insights.","required":["start_time","end_time"]},"v1ScheduleEnd":{"type":"object","properties":{"end_type":{"$ref":"#/components/schemas/v1ScheduleEndType"},"end_date":{"$ref":"#/components/schemas/typeDate"},"max_occurrences":{"type":"integer","format":"int32","description":"Number of occurrences when end_type is SCHEDULE_END_TYPE_AFTER_OCCURRENCES.\nSchedule stops after this many executions."}},"description":"ScheduleEnd defines when the schedule stops running.","required":["end_type"]},"v1ScheduleEndType":{"type":"string","enum":["SCHEDULE_END_TYPE_UNSPECIFIED","SCHEDULE_END_TYPE_NEVER","SCHEDULE_END_TYPE_ON_DATE","SCHEDULE_END_TYPE_AFTER_OCCURRENCES"],"default":"SCHEDULE_END_TYPE_UNSPECIFIED","description":"ScheduleEndType defines how a schedule terminates.\n\n - SCHEDULE_END_TYPE_UNSPECIFIED: Unspecified end type. Defaults to NEVER.\n - SCHEDULE_END_TYPE_NEVER: Schedule runs indefinitely (never ends).\n - SCHEDULE_END_TYPE_ON_DATE: Schedule ends on a specific date.\n - SCHEDULE_END_TYPE_AFTER_OCCURRENCES: Schedule ends after a specific number of occurrences."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"EnableAutomationScheduleBody":{"type":"object","description":"EnableAutomationScheduleRequest is the request to enable a previously disabled schedule."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}:enableAutomationSchedule":{"post":{"summary":"Enable Automation Schedule","operationId":"EnableAutomationSchedule","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1EnableAutomationScheduleResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnableAutomationScheduleBody"}}},"required":true},"tags":["Automations"]}}}} ``` ## Delete Workspace Connection > This API validates that the connection is not in use by any published\ > automations before deletion. If only draft automations use the connection,\ > deletion proceeds and returns the list of affected automations.\ > \ > The affected draft automations will have unresolved connection references\ > after deletion. They can still be edited but cannot be published until\ > new connections are configured.\ > \ > Errors:\ > \- FAILED\_PRECONDITION: Connection is in use by one or more published automations.\ > The error details include DeleteConnectionBlockedError with blocking automations.\ > \- NOT\_FOUND: Connection not found in the workspace.\ > \- INTERNAL: Failed to communicate with the connection storage service. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1DeleteWorkspaceConnectionResponse":{"type":"object","properties":{"affected_automations":{"type":"array","items":{"$ref":"#/components/schemas/v1AffectedAutomation"},"description":"List of draft automations that were affected by the deletion.\nThese automations have connection references that are now unresolved.\nEmpty if no draft automations were using the connection.","readOnly":true}},"description":"DeleteWorkspaceConnectionResponse returns information about affected automations."},"v1AffectedAutomation":{"type":"object","properties":{"automation_id":{"type":"string","description":"The automation ID (the {automation} segment of the resource name).","readOnly":true},"display_name":{"type":"string","description":"The human-readable display name of the automation.","readOnly":true}},"description":"AffectedAutomation describes a draft automation affected by connection deletion."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations:deleteConnection":{"delete":{"summary":"Delete Workspace Connection","description":"This API validates that the connection is not in use by any published\nautomations before deletion. If only draft automations use the connection,\ndeletion proceeds and returns the list of affected automations.\n\nThe affected draft automations will have unresolved connection references\nafter deletion. They can still be edited but cannot be published until\nnew connections are configured.\n\nErrors:\n- FAILED_PRECONDITION: Connection is in use by one or more published automations.\n The error details include DeleteConnectionBlockedError with blocking automations.\n- NOT_FOUND: Connection not found in the workspace.\n- INTERNAL: Failed to communicate with the connection storage service.","operationId":"DeleteWorkspaceConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1DeleteWorkspaceConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","description":"The connection ID to delete.","in":"query","required":true,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/triggers > List Automation Triggers ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListAutomationTriggersResponse":{"type":"object","properties":{"automation_triggers":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationTrigger"},"description":"List of triggers that are active for the specified automation."},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages."}},"description":"Response containing the list of active triggers for an automation."},"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers":{"get":{"summary":"List Automation Triggers","operationId":"ListAutomationTriggers","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListAutomationTriggersResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of triggers to return in a single response.\nThe service may return fewer than this value.\nIf unspecified, a default page size will be used.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListAutomationTriggers` call.\nProvide this to retrieve the subsequent page of results.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"A filter expression to apply to the list of triggers.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Automations"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/triggers > Create Automation Trigger ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Automations","description":"Create and configure automations, revisions, schedules, triggers, and connections."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1AutomationTrigger":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The external trigger ID created by another service.\nThis ID uniquely identifies the trigger in the external system."},"automation":{"type":"string","title":"Reference to the automation to be triggered.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"input_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Input mapping for the automation execution.\nKeys are input parameter names, values are the corresponding values to pass."},"phase_type":{"$ref":"#/components/schemas/v1PhaseType"},"phase_sub_type":{"$ref":"#/components/schemas/v1PhaseSubType"},"is_active":{"type":"boolean","description":"Whether this trigger is currently active."}},"description":"AutomationTrigger represents phase configuration metadata for an external trigger.\nThe trigger itself is created and managed by another service; this message\nstores additional metadata about how the trigger relates to automation phases.","required":["trigger_id","phase_type"]},"v1PhaseType":{"type":"string","enum":["PHASE_TYPE_UNSPECIFIED","PHASE_TYPE_PRE","PHASE_TYPE_MAIN","PHASE_TYPE_POST"],"default":"PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - PHASE_TYPE_PRE: Pre-processing phase.\n - PHASE_TYPE_MAIN: Main processing phase.\n - PHASE_TYPE_POST: Post-processing phase."},"v1PhaseSubType":{"type":"string","enum":["PHASE_SUB_TYPE_UNSPECIFIED","PHASE_SUB_TYPE_EMAIL","PHASE_SUB_TYPE_SCHEDULE","PHASE_SUB_TYPE_WEBHOOK","PHASE_SUB_TYPE_API"],"default":"PHASE_SUB_TYPE_UNSPECIFIED","description":"PhaseSubType defines the sub-type within a phase for an automation trigger.\n\n - PHASE_SUB_TYPE_UNSPECIFIED: Unspecified phase sub-type.\n - PHASE_SUB_TYPE_EMAIL: Email trigger sub-type.\n - PHASE_SUB_TYPE_SCHEDULE: Schedule-based trigger sub-type.\n - PHASE_SUB_TYPE_WEBHOOK: Webhook trigger sub-type.\n - PHASE_SUB_TYPE_API: API trigger sub-type."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/triggers":{"post":{"summary":"Create Automation Trigger","operationId":"CreateAutomationTrigger","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationTrigger"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1AutomationTrigger"}}},"description":"The trigger phase configuration to store.","required":true},"tags":["Automations"]}}}} ``` # Runs Execute automations and manage run lifecycle — start, pause, continue, and view events. ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id} > Get Run ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Run":{"type":"object","properties":{"name":{"type":"string","title":"The name of the run.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"executable_steps":{"$ref":"#/components/schemas/v1ExecutableSteps"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when this run was created.\nSet automatically when the run is first submitted to the system.","readOnly":true},"state":{"$ref":"#/components/schemas/v1RunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when this run was updated.\nSet automatically when the run is updated.","readOnly":true},"previous_run":{"type":"string","title":"The name of the previous run in the chain, if applicable.\nExecution details of the previous run may be used to avoid re-computation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"stage_version":{"type":"string","description":"The version of the automation stage at the time this run was created."},"invocation_details":{"$ref":"#/components/schemas/v1InvocationDetails"},"user_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The user inputs provided to the run during pre phase and will be available for the UI to display the user inputs."}},"description":"Run represents a single execution instance of code in the Jeeves platform.\nContains the executable code, metadata, and current execution state.","required":["stage","stage_version"]},"v1ExecutableSteps":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input parameters for the execution, provided as name-value pairs.\nThese variables will be available to the code during execution."},"executables":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutableStep"},"description":"The source code to be executed, written in SPy (Simplified Python) language."}},"description":"ExecutableSteps represents a sequence of steps of execution of a run. Each step is\na separate computable unit with its own code, book connections and optional inputs.\nThe first step may optionally have an input provided to it when the run is invoked.\nThe output of each step becomes the input of the next step and the output of the\nlast step becomes the output of the run.","required":["executables"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1ExecutableStep":{"type":"object","properties":{"code":{"type":"string","description":"The source code to be executed, written in SPy (Simplified Python) language.\nThis is the main logic that will be interpreted and run by the execution engine."},"book_connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this executable.\nMaps connection names to their specific ID and endpoints."},"phase_type":{"$ref":"#/components/schemas/v1AutomationPhaseType"}},"description":"ExecutableStep represents a piece of code that can be executed in the Jeeves platform.\nContains the source code, input parameters, and external dependencies needed for execution.","required":["code","phase_type"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationPhaseType":{"type":"string","enum":["AUTOMATION_PHASE_TYPE_UNSPECIFIED","AUTOMATION_PHASE_TYPE_PRE","AUTOMATION_PHASE_TYPE_MAIN","AUTOMATION_PHASE_TYPE_POST"],"default":"AUTOMATION_PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - AUTOMATION_PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - AUTOMATION_PHASE_TYPE_PRE: Pre-processing phase.\n - AUTOMATION_PHASE_TYPE_MAIN: Main processing phase.\n - AUTOMATION_PHASE_TYPE_POST: Post-processing phase."},"v1RunState":{"type":"object","properties":{"pending":{"$ref":"#/components/schemas/v1PendingRunState"},"executing":{"$ref":"#/components/schemas/v1ExecutingRunState"},"stopping":{"$ref":"#/components/schemas/v1StoppingRunState"},"stopped":{"$ref":"#/components/schemas/v1StoppedRunState"},"awaiting_guidance":{"$ref":"#/components/schemas/v1AwaitingGuidanceRunState"},"completed":{"$ref":"#/components/schemas/v1CompletedRunState"},"failed":{"$ref":"#/components/schemas/v1FailedRunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the run transitioned to this state.","readOnly":true}},"description":"RunState represents the overall lifecycle state of a run.\nTracks the run from initial submission through completion or failure."},"v1PendingRunState":{"type":"object","description":"Run has been submitted and is waiting to start execution.\nThe run is queued and will begin when resources become available."},"v1ExecutingRunState":{"type":"object","description":"Run is currently being executed.\nCode is actively running and making progress."},"v1StoppingRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run is in the process of being stopped.\nExecution is stopping gracefully and will transition to STOPPED state."},"v1StoppedRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run has been stopped and can be resumed later.\nExecution is temporarily stopped but can continue from current state."},"v1AwaitingGuidanceRunState":{"type":"object","properties":{"exception":{"type":"string","title":"ID of the exception (from guidance center)","readOnly":true},"description":{"type":"string","description":"Description of the exception that occured.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run is waiting for external guidance or user input.\nRequires manual intervention or external decision to proceed."},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CompletedRunState":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The outputs of the run.","readOnly":true}},"description":"Run has completed successfully.\nAll code has been executed and results are available."},"v1FailedRunState":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the error that caused the run to fail.","readOnly":true},"description":{"type":"string","description":"The description of the error.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run has failed due to an error.\nExecution stopped due to an unrecoverable error condition."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"v1InvocationDetails":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The ID of the trigger that initiated this run, if applicable."},"user_id":{"type":"string","description":"The ID of the user that initiated this run, if applicable."},"invocation_source":{"$ref":"#/components/schemas/v1InvocationSource"}},"description":"InvocationDetails contains additional information about the entity that initiated a run."},"v1InvocationSource":{"type":"string","enum":["INVOCATION_SOURCE_UNSPECIFIED","INVOCATION_SOURCE_MANUAL","INVOCATION_SOURCE_TRIGGER","INVOCATION_SOURCE_SCHEDULE"],"default":"INVOCATION_SOURCE_UNSPECIFIED","description":"InvocationSource identifies the entity responsible for creating a run.\n\n - INVOCATION_SOURCE_UNSPECIFIED: Unspecified invocation source.\n - INVOCATION_SOURCE_MANUAL: Run was manually initiated by a user.\n - INVOCATION_SOURCE_TRIGGER: Run was triggered by an event or trigger.\n - INVOCATION_SOURCE_SCHEDULE: Run was initiated by a schedule."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}":{"get":{"summary":"Get Run","operationId":"GetRun","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Run"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Runs"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs > List Runs ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListRunsResponse":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/v1Run"},"description":"The list of runs matching the request criteria.\nMay be empty if no runs are found or if the page is beyond available results.","readOnly":true},"next_page_token":{"type":"string","description":"A token that can be sent as `page_token` to retrieve the next page.\nIf this field is omitted, there are no subsequent pages.","readOnly":true}},"description":"Response message for ListRuns method.\nContains a paginated list of runs and pagination metadata."},"v1Run":{"type":"object","properties":{"name":{"type":"string","title":"The name of the run.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"executable_steps":{"$ref":"#/components/schemas/v1ExecutableSteps"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when this run was created.\nSet automatically when the run is first submitted to the system.","readOnly":true},"state":{"$ref":"#/components/schemas/v1RunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when this run was updated.\nSet automatically when the run is updated.","readOnly":true},"previous_run":{"type":"string","title":"The name of the previous run in the chain, if applicable.\nExecution details of the previous run may be used to avoid re-computation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"stage_version":{"type":"string","description":"The version of the automation stage at the time this run was created."},"invocation_details":{"$ref":"#/components/schemas/v1InvocationDetails"},"user_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The user inputs provided to the run during pre phase and will be available for the UI to display the user inputs."}},"description":"Run represents a single execution instance of code in the Jeeves platform.\nContains the executable code, metadata, and current execution state.","required":["stage","stage_version"]},"v1ExecutableSteps":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input parameters for the execution, provided as name-value pairs.\nThese variables will be available to the code during execution."},"executables":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutableStep"},"description":"The source code to be executed, written in SPy (Simplified Python) language."}},"description":"ExecutableSteps represents a sequence of steps of execution of a run. Each step is\na separate computable unit with its own code, book connections and optional inputs.\nThe first step may optionally have an input provided to it when the run is invoked.\nThe output of each step becomes the input of the next step and the output of the\nlast step becomes the output of the run.","required":["executables"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1ExecutableStep":{"type":"object","properties":{"code":{"type":"string","description":"The source code to be executed, written in SPy (Simplified Python) language.\nThis is the main logic that will be interpreted and run by the execution engine."},"book_connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this executable.\nMaps connection names to their specific ID and endpoints."},"phase_type":{"$ref":"#/components/schemas/v1AutomationPhaseType"}},"description":"ExecutableStep represents a piece of code that can be executed in the Jeeves platform.\nContains the source code, input parameters, and external dependencies needed for execution.","required":["code","phase_type"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationPhaseType":{"type":"string","enum":["AUTOMATION_PHASE_TYPE_UNSPECIFIED","AUTOMATION_PHASE_TYPE_PRE","AUTOMATION_PHASE_TYPE_MAIN","AUTOMATION_PHASE_TYPE_POST"],"default":"AUTOMATION_PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - AUTOMATION_PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - AUTOMATION_PHASE_TYPE_PRE: Pre-processing phase.\n - AUTOMATION_PHASE_TYPE_MAIN: Main processing phase.\n - AUTOMATION_PHASE_TYPE_POST: Post-processing phase."},"v1RunState":{"type":"object","properties":{"pending":{"$ref":"#/components/schemas/v1PendingRunState"},"executing":{"$ref":"#/components/schemas/v1ExecutingRunState"},"stopping":{"$ref":"#/components/schemas/v1StoppingRunState"},"stopped":{"$ref":"#/components/schemas/v1StoppedRunState"},"awaiting_guidance":{"$ref":"#/components/schemas/v1AwaitingGuidanceRunState"},"completed":{"$ref":"#/components/schemas/v1CompletedRunState"},"failed":{"$ref":"#/components/schemas/v1FailedRunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the run transitioned to this state.","readOnly":true}},"description":"RunState represents the overall lifecycle state of a run.\nTracks the run from initial submission through completion or failure."},"v1PendingRunState":{"type":"object","description":"Run has been submitted and is waiting to start execution.\nThe run is queued and will begin when resources become available."},"v1ExecutingRunState":{"type":"object","description":"Run is currently being executed.\nCode is actively running and making progress."},"v1StoppingRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run is in the process of being stopped.\nExecution is stopping gracefully and will transition to STOPPED state."},"v1StoppedRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run has been stopped and can be resumed later.\nExecution is temporarily stopped but can continue from current state."},"v1AwaitingGuidanceRunState":{"type":"object","properties":{"exception":{"type":"string","title":"ID of the exception (from guidance center)","readOnly":true},"description":{"type":"string","description":"Description of the exception that occured.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run is waiting for external guidance or user input.\nRequires manual intervention or external decision to proceed."},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CompletedRunState":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The outputs of the run.","readOnly":true}},"description":"Run has completed successfully.\nAll code has been executed and results are available."},"v1FailedRunState":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the error that caused the run to fail.","readOnly":true},"description":{"type":"string","description":"The description of the error.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run has failed due to an error.\nExecution stopped due to an unrecoverable error condition."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"v1InvocationDetails":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The ID of the trigger that initiated this run, if applicable."},"user_id":{"type":"string","description":"The ID of the user that initiated this run, if applicable."},"invocation_source":{"$ref":"#/components/schemas/v1InvocationSource"}},"description":"InvocationDetails contains additional information about the entity that initiated a run."},"v1InvocationSource":{"type":"string","enum":["INVOCATION_SOURCE_UNSPECIFIED","INVOCATION_SOURCE_MANUAL","INVOCATION_SOURCE_TRIGGER","INVOCATION_SOURCE_SCHEDULE"],"default":"INVOCATION_SOURCE_UNSPECIFIED","description":"InvocationSource identifies the entity responsible for creating a run.\n\n - INVOCATION_SOURCE_UNSPECIFIED: Unspecified invocation source.\n - INVOCATION_SOURCE_MANUAL: Run was manually initiated by a user.\n - INVOCATION_SOURCE_TRIGGER: Run was triggered by an event or trigger.\n - INVOCATION_SOURCE_SCHEDULE: Run was initiated by a schedule."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs":{"get":{"summary":"List Runs","operationId":"ListRuns","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListRunsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of runs to return in a single response.\nThe service may return fewer than this value.\nIf unspecified or 0, at most 10 runs will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nIf negative, an INVALID_ARGUMENT error will be returned.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"A page token received from a previous `ListRuns` call.\nProvide this to retrieve the subsequent page of results.\nWhen paginating, all other parameters provided to `ListRuns` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression for filtering runs.\nFollows the structured syntax defined in AIP-160.\n\nSupported fields for filtering:\n- create_time: The timestamp when the run was created (google.protobuf.Timestamp)\n\nSupported operators:\n- Comparison: =, !=, <, >, <=, >=\n- Logical: AND, OR, NOT, -\n\nExamples:\n- Filter runs created after a specific date (start_date):\n \"create_time >= \\\"2024-01-01T00:00:00Z\\\"\"\n- Filter runs created before a specific date (end_date):\n \"create_time <= \\\"2024-12-31T23:59:59Z\\\"\"\n- Filter runs within a date range (start_date and end_date):\n \"create_time >= \\\"2024-01-01T00:00:00Z\\\" AND create_time <= \\\"2024-12-31T23:59:59Z\\\"\"\n- Complex filter with multiple date ranges:\n \"(create_time >= \\\"2024-01-01T00:00:00Z\\\" AND create_time <= \\\"2024-06-30T23:59:59Z\\\") OR create_time >= \\\"2024-07-01T00:00:00Z\\\"\"\n\nTimestamps must be in RFC-3339 format (e.g., \"2024-01-01T00:00:00Z\").\nIf an invalid filter expression is provided, the API will return INVALID_ARGUMENT.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Runs"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}:pause > Pause Run ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Run":{"type":"object","properties":{"name":{"type":"string","title":"The name of the run.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"executable_steps":{"$ref":"#/components/schemas/v1ExecutableSteps"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when this run was created.\nSet automatically when the run is first submitted to the system.","readOnly":true},"state":{"$ref":"#/components/schemas/v1RunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when this run was updated.\nSet automatically when the run is updated.","readOnly":true},"previous_run":{"type":"string","title":"The name of the previous run in the chain, if applicable.\nExecution details of the previous run may be used to avoid re-computation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"stage_version":{"type":"string","description":"The version of the automation stage at the time this run was created."},"invocation_details":{"$ref":"#/components/schemas/v1InvocationDetails"},"user_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The user inputs provided to the run during pre phase and will be available for the UI to display the user inputs."}},"description":"Run represents a single execution instance of code in the Jeeves platform.\nContains the executable code, metadata, and current execution state.","required":["stage","stage_version"]},"v1ExecutableSteps":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input parameters for the execution, provided as name-value pairs.\nThese variables will be available to the code during execution."},"executables":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutableStep"},"description":"The source code to be executed, written in SPy (Simplified Python) language."}},"description":"ExecutableSteps represents a sequence of steps of execution of a run. Each step is\na separate computable unit with its own code, book connections and optional inputs.\nThe first step may optionally have an input provided to it when the run is invoked.\nThe output of each step becomes the input of the next step and the output of the\nlast step becomes the output of the run.","required":["executables"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1ExecutableStep":{"type":"object","properties":{"code":{"type":"string","description":"The source code to be executed, written in SPy (Simplified Python) language.\nThis is the main logic that will be interpreted and run by the execution engine."},"book_connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this executable.\nMaps connection names to their specific ID and endpoints."},"phase_type":{"$ref":"#/components/schemas/v1AutomationPhaseType"}},"description":"ExecutableStep represents a piece of code that can be executed in the Jeeves platform.\nContains the source code, input parameters, and external dependencies needed for execution.","required":["code","phase_type"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationPhaseType":{"type":"string","enum":["AUTOMATION_PHASE_TYPE_UNSPECIFIED","AUTOMATION_PHASE_TYPE_PRE","AUTOMATION_PHASE_TYPE_MAIN","AUTOMATION_PHASE_TYPE_POST"],"default":"AUTOMATION_PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - AUTOMATION_PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - AUTOMATION_PHASE_TYPE_PRE: Pre-processing phase.\n - AUTOMATION_PHASE_TYPE_MAIN: Main processing phase.\n - AUTOMATION_PHASE_TYPE_POST: Post-processing phase."},"v1RunState":{"type":"object","properties":{"pending":{"$ref":"#/components/schemas/v1PendingRunState"},"executing":{"$ref":"#/components/schemas/v1ExecutingRunState"},"stopping":{"$ref":"#/components/schemas/v1StoppingRunState"},"stopped":{"$ref":"#/components/schemas/v1StoppedRunState"},"awaiting_guidance":{"$ref":"#/components/schemas/v1AwaitingGuidanceRunState"},"completed":{"$ref":"#/components/schemas/v1CompletedRunState"},"failed":{"$ref":"#/components/schemas/v1FailedRunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the run transitioned to this state.","readOnly":true}},"description":"RunState represents the overall lifecycle state of a run.\nTracks the run from initial submission through completion or failure."},"v1PendingRunState":{"type":"object","description":"Run has been submitted and is waiting to start execution.\nThe run is queued and will begin when resources become available."},"v1ExecutingRunState":{"type":"object","description":"Run is currently being executed.\nCode is actively running and making progress."},"v1StoppingRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run is in the process of being stopped.\nExecution is stopping gracefully and will transition to STOPPED state."},"v1StoppedRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run has been stopped and can be resumed later.\nExecution is temporarily stopped but can continue from current state."},"v1AwaitingGuidanceRunState":{"type":"object","properties":{"exception":{"type":"string","title":"ID of the exception (from guidance center)","readOnly":true},"description":{"type":"string","description":"Description of the exception that occured.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run is waiting for external guidance or user input.\nRequires manual intervention or external decision to proceed."},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CompletedRunState":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The outputs of the run.","readOnly":true}},"description":"Run has completed successfully.\nAll code has been executed and results are available."},"v1FailedRunState":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the error that caused the run to fail.","readOnly":true},"description":{"type":"string","description":"The description of the error.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run has failed due to an error.\nExecution stopped due to an unrecoverable error condition."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"v1InvocationDetails":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The ID of the trigger that initiated this run, if applicable."},"user_id":{"type":"string","description":"The ID of the user that initiated this run, if applicable."},"invocation_source":{"$ref":"#/components/schemas/v1InvocationSource"}},"description":"InvocationDetails contains additional information about the entity that initiated a run."},"v1InvocationSource":{"type":"string","enum":["INVOCATION_SOURCE_UNSPECIFIED","INVOCATION_SOURCE_MANUAL","INVOCATION_SOURCE_TRIGGER","INVOCATION_SOURCE_SCHEDULE"],"default":"INVOCATION_SOURCE_UNSPECIFIED","description":"InvocationSource identifies the entity responsible for creating a run.\n\n - INVOCATION_SOURCE_UNSPECIFIED: Unspecified invocation source.\n - INVOCATION_SOURCE_MANUAL: Run was manually initiated by a user.\n - INVOCATION_SOURCE_TRIGGER: Run was triggered by an event or trigger.\n - INVOCATION_SOURCE_SCHEDULE: Run was initiated by a schedule."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"PauseRunBody":{"type":"object","properties":{"reason":{"type":"string","description":"The reason for pausing the run."}},"description":"Request message for PauseRun method.\nSpecifies which run to pause by its unique identifier.","required":["reason"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:pause":{"post":{"summary":"Pause Run","operationId":"PauseRun","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Run"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseRunBody"}}},"required":true},"tags":["Runs"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}:continue > Continue Run ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Run":{"type":"object","properties":{"name":{"type":"string","title":"The name of the run.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"executable_steps":{"$ref":"#/components/schemas/v1ExecutableSteps"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when this run was created.\nSet automatically when the run is first submitted to the system.","readOnly":true},"state":{"$ref":"#/components/schemas/v1RunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when this run was updated.\nSet automatically when the run is updated.","readOnly":true},"previous_run":{"type":"string","title":"The name of the previous run in the chain, if applicable.\nExecution details of the previous run may be used to avoid re-computation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"stage_version":{"type":"string","description":"The version of the automation stage at the time this run was created."},"invocation_details":{"$ref":"#/components/schemas/v1InvocationDetails"},"user_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The user inputs provided to the run during pre phase and will be available for the UI to display the user inputs."}},"description":"Run represents a single execution instance of code in the Jeeves platform.\nContains the executable code, metadata, and current execution state.","required":["stage","stage_version"]},"v1ExecutableSteps":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input parameters for the execution, provided as name-value pairs.\nThese variables will be available to the code during execution."},"executables":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutableStep"},"description":"The source code to be executed, written in SPy (Simplified Python) language."}},"description":"ExecutableSteps represents a sequence of steps of execution of a run. Each step is\na separate computable unit with its own code, book connections and optional inputs.\nThe first step may optionally have an input provided to it when the run is invoked.\nThe output of each step becomes the input of the next step and the output of the\nlast step becomes the output of the run.","required":["executables"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1ExecutableStep":{"type":"object","properties":{"code":{"type":"string","description":"The source code to be executed, written in SPy (Simplified Python) language.\nThis is the main logic that will be interpreted and run by the execution engine."},"book_connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this executable.\nMaps connection names to their specific ID and endpoints."},"phase_type":{"$ref":"#/components/schemas/v1AutomationPhaseType"}},"description":"ExecutableStep represents a piece of code that can be executed in the Jeeves platform.\nContains the source code, input parameters, and external dependencies needed for execution.","required":["code","phase_type"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationPhaseType":{"type":"string","enum":["AUTOMATION_PHASE_TYPE_UNSPECIFIED","AUTOMATION_PHASE_TYPE_PRE","AUTOMATION_PHASE_TYPE_MAIN","AUTOMATION_PHASE_TYPE_POST"],"default":"AUTOMATION_PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - AUTOMATION_PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - AUTOMATION_PHASE_TYPE_PRE: Pre-processing phase.\n - AUTOMATION_PHASE_TYPE_MAIN: Main processing phase.\n - AUTOMATION_PHASE_TYPE_POST: Post-processing phase."},"v1RunState":{"type":"object","properties":{"pending":{"$ref":"#/components/schemas/v1PendingRunState"},"executing":{"$ref":"#/components/schemas/v1ExecutingRunState"},"stopping":{"$ref":"#/components/schemas/v1StoppingRunState"},"stopped":{"$ref":"#/components/schemas/v1StoppedRunState"},"awaiting_guidance":{"$ref":"#/components/schemas/v1AwaitingGuidanceRunState"},"completed":{"$ref":"#/components/schemas/v1CompletedRunState"},"failed":{"$ref":"#/components/schemas/v1FailedRunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the run transitioned to this state.","readOnly":true}},"description":"RunState represents the overall lifecycle state of a run.\nTracks the run from initial submission through completion or failure."},"v1PendingRunState":{"type":"object","description":"Run has been submitted and is waiting to start execution.\nThe run is queued and will begin when resources become available."},"v1ExecutingRunState":{"type":"object","description":"Run is currently being executed.\nCode is actively running and making progress."},"v1StoppingRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run is in the process of being stopped.\nExecution is stopping gracefully and will transition to STOPPED state."},"v1StoppedRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run has been stopped and can be resumed later.\nExecution is temporarily stopped but can continue from current state."},"v1AwaitingGuidanceRunState":{"type":"object","properties":{"exception":{"type":"string","title":"ID of the exception (from guidance center)","readOnly":true},"description":{"type":"string","description":"Description of the exception that occured.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run is waiting for external guidance or user input.\nRequires manual intervention or external decision to proceed."},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CompletedRunState":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The outputs of the run.","readOnly":true}},"description":"Run has completed successfully.\nAll code has been executed and results are available."},"v1FailedRunState":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the error that caused the run to fail.","readOnly":true},"description":{"type":"string","description":"The description of the error.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run has failed due to an error.\nExecution stopped due to an unrecoverable error condition."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"v1InvocationDetails":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The ID of the trigger that initiated this run, if applicable."},"user_id":{"type":"string","description":"The ID of the user that initiated this run, if applicable."},"invocation_source":{"$ref":"#/components/schemas/v1InvocationSource"}},"description":"InvocationDetails contains additional information about the entity that initiated a run."},"v1InvocationSource":{"type":"string","enum":["INVOCATION_SOURCE_UNSPECIFIED","INVOCATION_SOURCE_MANUAL","INVOCATION_SOURCE_TRIGGER","INVOCATION_SOURCE_SCHEDULE"],"default":"INVOCATION_SOURCE_UNSPECIFIED","description":"InvocationSource identifies the entity responsible for creating a run.\n\n - INVOCATION_SOURCE_UNSPECIFIED: Unspecified invocation source.\n - INVOCATION_SOURCE_MANUAL: Run was manually initiated by a user.\n - INVOCATION_SOURCE_TRIGGER: Run was triggered by an event or trigger.\n - INVOCATION_SOURCE_SCHEDULE: Run was initiated by a schedule."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"ContinueRunBody":{"type":"object","description":"Request message for ContinueRun method.\nSpecifies which run to resume by its unique identifier."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}:continue":{"post":{"summary":"Continue Run","operationId":"ContinueRun","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Run"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContinueRunBody"}}},"required":true},"tags":["Runs"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}:automationRunAggregates > Query Automation Run Aggregates ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1QueryAutomationRunAggregatesResponse":{"type":"object","properties":{"automation_run_aggregates":{"type":"array","items":{"$ref":"#/components/schemas/v1AutomationRunAggregateEntry"},"description":"List of automation run statistics entries.","readOnly":true}},"description":"Response message for QueryAutomationRunAggregates method.\nContains statistics for each automation in the workspace."},"v1AutomationRunAggregateEntry":{"type":"object","properties":{"automation_id":{"type":"string","title":"The automation ID for this entry.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"stats":{"$ref":"#/components/schemas/v1AutomationRunAggregate"}},"description":"Entry for automation run statistics.\nContains the automation ID and its associated run counts."},"v1AutomationRunAggregate":{"type":"object","properties":{"total_runs":{"type":"string","format":"int64","description":"The total number of runs for this automation.","readOnly":true},"completed_runs":{"type":"string","format":"int64","description":"The number of completed runs for this automation.","readOnly":true}},"description":"Stats for a single automation.\nContains run counts and other metrics."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}:automationRunAggregates":{"get":{"summary":"Query Automation Run Aggregates","operationId":"QueryAutomationRunAggregates","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1QueryAutomationRunAggregatesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Runs"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}:dailyRunAggregates > Query Daily Run Aggregates ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1QueryDailyRunAggregatesResponse":{"type":"object","properties":{"daily_run_aggregates":{"type":"array","items":{"$ref":"#/components/schemas/v1DailyRunAggregateEntry"},"description":"List of daily run statistics entries.","readOnly":true}},"description":"Response message for QueryDailyRunAggregates method.\nContains daily run statistics as a list of entries."},"v1DailyRunAggregateEntry":{"type":"object","properties":{"date":{"type":"string","description":"The date for this entry.\nFormat: YYYY-MM-DD (e.g., \"2024-01-01\"). Using google.type.Date causing issue while transcoding to json.","readOnly":true},"stats":{"$ref":"#/components/schemas/v1DailyRunAggregate"}},"description":"Entry for daily run statistics.\nContains the date and run counts for that date."},"v1DailyRunAggregate":{"type":"object","properties":{"total_runs":{"type":"integer","format":"int32","description":"The total number of runs created on this date.","readOnly":true}},"description":"Stats for a single day.\nContains run counts for all runs in the workspace on that date."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}:dailyRunAggregates":{"get":{"summary":"Query Daily Run Aggregates","operationId":"QueryDailyRunAggregates","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1QueryDailyRunAggregatesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"start_date.year","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"start_date.month","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"start_date.day","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"end_date.year","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"end_date.month","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"end_date.day","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"time_zone","description":"Time zone for date aggregation.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"UTC\", \"Europe/London\")","in":"query","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression for filtering runs included in the aggregation.\nFollows the structured syntax defined in AIP-160.\n\nSupported fields for filtering:\n- automation_id: The unique identifier of the automation (string)\n\nSupported operators:\n- Comparison: =\n- Logical: OR\n\nExamples:\n- Filter by specific automation:\n \"automation_id = \\\"789\\\"\"\n- Filter by multiple automations:\n \"automation_id = \\\"789\\\" OR automation_id = \\\"790\\\"\"\n\nIf an invalid filter expression is provided, the API will return INVALID_ARGUMENT.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Runs"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/executions/{execution\_id}/outputs > Get Execution Outputs ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GetExecutionOutputsResponse":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1ExecutionOutput"},"description":"Map of named output values set by the set_output() builtin function during execution.\nThe key is the output name (string) and the value is the ExecutionOutput containing\nthe value and type set by calling set_output(name, value).\nThis map will be empty if no set_output() calls were made during execution."}},"description":"GetExecutionOutputsResponse contains the outputs from a completed execution."},"v1ExecutionOutput":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/commonV1Value"},"type":{"$ref":"#/components/schemas/v1ValueType"}},"description":"ExecutionOutput represents an output value set by the set_output() builtin function during execution."},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1ValueType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v1ValueScalarType"},"optional_type":{"$ref":"#/components/schemas/v1ValueOptionalType"},"list_type":{"$ref":"#/components/schemas/v1ValueListType"},"dictionary_type":{"$ref":"#/components/schemas/v1ValueDictionaryType"},"table_type":{"$ref":"#/components/schemas/v1ValueTableType"},"opaque_type":{"$ref":"#/components/schemas/v1ValueOpaqueType"},"any_type":{"$ref":"#/components/schemas/v1ValueAnyType"},"union_type":{"$ref":"#/components/schemas/v1ValueUnionType"},"sensitive_type":{"$ref":"#/components/schemas/v1ValueSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v1ValueEnumType"},"generic_dictionary_type":{"$ref":"#/components/schemas/v1ValueGenericDictionaryType"}},"title":"Represents a complete value type definition using a discriminated union"},"v1ValueScalarType":{"type":"string","enum":["VALUE_SCALAR_TYPE_UNSPECIFIED","VALUE_SCALAR_TYPE_TEXT","VALUE_SCALAR_TYPE_NUMBER","VALUE_SCALAR_TYPE_BOOLEAN","VALUE_SCALAR_TYPE_DATETIME","VALUE_SCALAR_TYPE_DATE","VALUE_SCALAR_TYPE_TIME","VALUE_SCALAR_TYPE_FILE"],"default":"VALUE_SCALAR_TYPE_UNSPECIFIED","description":"- VALUE_SCALAR_TYPE_UNSPECIFIED: Unspecified value type\n - VALUE_SCALAR_TYPE_TEXT: A text value type\n - VALUE_SCALAR_TYPE_NUMBER: A number value type\n - VALUE_SCALAR_TYPE_BOOLEAN: A boolean value type\n - VALUE_SCALAR_TYPE_DATETIME: A datetime value type\n - VALUE_SCALAR_TYPE_DATE: A date value type\n - VALUE_SCALAR_TYPE_TIME: A time value type\n - VALUE_SCALAR_TYPE_FILE: A file value type","title":"Supported Value Scalar Types"},"v1ValueOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that can be optional (nullable)"},"v1ValueListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a list/array value type containing elements of a specific type"},"v1ValueDictionaryType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this dictionary represents"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueDictionaryTypeField"},"title":"The named fields contained in this dictionary"},"description":{"type":"string","title":"Optional human-readable description of this dictionary type"}},"title":"Represents a dictionary/object value type with named fields"},"v1ValueDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this field"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this field"}},"title":"Represents a single field within a dictionary value type"},"v1ValueTableType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this table represents"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueTableTypeColumn"},"title":"The columns that make up this table"},"description":{"type":"string","title":"Optional human-readable description of this table type"}},"title":"Represents a table value type with structured columns"},"v1ValueTableTypeColumn":{"type":"object","properties":{"key":{"type":"string","title":"The name/key of this column"},"value":{"$ref":"#/components/schemas/v1ValueType"},"description":{"type":"string","title":"Optional human-readable description of this column"}},"title":"Represents a single column within a table value type"},"v1ValueOpaqueType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this opaque type represents"},"description":{"type":"string","title":"Optional human-readable description of this opaque type"}},"title":"Represents an opaque value type with semantic meaning but unknown internal structure"},"v1ValueAnyType":{"type":"object","title":"Represents a value type that can hold any kind of value"},"v1ValueUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueType"},"title":"The possible value types in this union"}},"title":"Represents a union value type that can be one of several possible types"},"v1ValueSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represents a value type that contains sensitive information"},"v1ValueEnumType":{"type":"object","properties":{"is_a":{"type":"string","title":"Semantic classification of what this enum represents"},"members":{"type":"array","items":{"$ref":"#/components/schemas/v1ValueEnumTypeMember"},"title":"The available options/members of this enum"},"description":{"type":"string","title":"Optional human-readable description of this enum type"}},"title":"Represents an enumeration value type with predefined options"},"v1ValueEnumTypeMember":{"type":"object","properties":{"name":{"type":"string","title":"The programmatic name of this enum member"},"description":{"type":"string","title":"Optional human-readable description of this enum member"}},"title":"Represents a single member/option within an enum value type"},"v1ValueGenericDictionaryType":{"type":"object","properties":{"key_type":{"$ref":"#/components/schemas/v1ValueType"},"value_type":{"$ref":"#/components/schemas/v1ValueType"}},"title":"Represent a generic dictionary that can hold any entry of a particular key and value type"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/executions/{execution_id}/outputs":{"get":{"summary":"Get Execution Outputs","operationId":"GetExecutionOutputs","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GetExecutionOutputsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"execution_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Runs"]}}}} ``` ## List Run Events > This RPC retrieves a paginated list of all events that occurred during\ > a specific automation run. Events are returned in the order they were\ > generated, providing a complete timeline of the run's execution.\ > \ > Use the filter parameter to narrow results by specific criteria such as\ > node\_kind for execution journal events.\ > \ > The response includes both high-level run state changes (starts, completions,\ > failures) and detailed execution steps (node executions, execution patches,\ > detailed data flows in each expression, etc). ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Execute automations and manage run lifecycle — start, pause, continue, and view events."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListRunEventsResponse":{"type":"object","properties":{"run_events":{"type":"array","items":{"$ref":"#/components/schemas/v1RunEvent"},"description":"The list of run events for the requested page.\n\nEvents are returned in chronological order based on when they occurred\nduring the automation run execution. Each event contains either:\n- A run state update from the Jeeves orchestration service\n- An execution journal entry from the Jarvis execution engine"},"next_page_token":{"type":"string","description":"Pagination token for retrieving the next page of events.\n\nInclude this token as the `page_token` in a subsequent ListRunEvents\nrequest to retrieve the next set of events. The token maintains\ncursor position and ensures consistent pagination even if new\nevents are added to the run.\n\nWhen this field is empty or omitted:\n- This is the final page of results\n- All events for the run have been retrieved\n- No further pagination requests are needed\n\nThe token is opaque. Do not attempt to parse, modify, or reuse tokens\nacross different parent resources or request parameters."}},"description":"Response message for the ListRunEvents RPC.\n\nContains a page of run events in chronological order, along with pagination\ninformation for retrieving additional events. Events are sorted by their\noccurrence time, providing a complete timeline of the run's execution.\n\nThe response may contain fewer events than requested if:\n- The run has fewer remaining events than the page size\n- This is the final page of results\n- Response size limits are reached"},"v1RunEvent":{"type":"object","properties":{"run_update":{"$ref":"#/components/schemas/v1RunUpdate"},"execution_journal":{"$ref":"#/components/schemas/v1ExecutionJournal"}},"description":"A single event that occurred during an automation run execution."},"v1RunUpdate":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/v1Run"}},"description":"RunUpdate represents a single update to a run's state."},"v1Run":{"type":"object","properties":{"name":{"type":"string","title":"The name of the run.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"executable_steps":{"$ref":"#/components/schemas/v1ExecutableSteps"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when this run was created.\nSet automatically when the run is first submitted to the system.","readOnly":true},"state":{"$ref":"#/components/schemas/v1RunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when this run was updated.\nSet automatically when the run is updated.","readOnly":true},"previous_run":{"type":"string","title":"The name of the previous run in the chain, if applicable.\nExecution details of the previous run may be used to avoid re-computation.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"stage_version":{"type":"string","description":"The version of the automation stage at the time this run was created."},"invocation_details":{"$ref":"#/components/schemas/v1InvocationDetails"},"user_inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The user inputs provided to the run during pre phase and will be available for the UI to display the user inputs."}},"description":"Run represents a single execution instance of code in the Jeeves platform.\nContains the executable code, metadata, and current execution state.","required":["stage","stage_version"]},"v1ExecutableSteps":{"type":"object","properties":{"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Input parameters for the execution, provided as name-value pairs.\nThese variables will be available to the code during execution."},"executables":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutableStep"},"description":"The source code to be executed, written in SPy (Simplified Python) language."}},"description":"ExecutableSteps represents a sequence of steps of execution of a run. Each step is\na separate computable unit with its own code, book connections and optional inputs.\nThe first step may optionally have an input provided to it when the run is invoked.\nThe output of each step becomes the input of the next step and the output of the\nlast step becomes the output of the run.","required":["executables"]},"commonV1Value":{"type":"object","properties":{"null_value":{"type":"string","title":"Represents the absence of a value (None/null/undefined)"},"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"},"duration":{"type":"string","title":"Signed duration representing a span of time"},"list":{"$ref":"#/components/schemas/v1List"},"dictionary":{"$ref":"#/components/schemas/v1Dictionary"},"file":{"$ref":"#/components/schemas/v1FileValue"},"table":{"$ref":"#/components/schemas/v1TableValue"},"set":{"$ref":"#/components/schemas/v1Set"}},"description":"Represents a runtime value that can be produced by the Jarvis interpreter.\n\nThis message provides a type-safe way to serialize and transmit values between\nthe Jarvis interpreter and other services via gRPC. It supports all the basic\ndata types that can be represented in the Jarvis language runtime.\n\nThe oneof structure ensures that exactly one value type is set at a time,\nproviding both type safety and efficient serialization."},"v1Number":{"type":"object","properties":{"lo":{"type":"integer","format":"int64","description":"Low 32 bits of the 96-bit mantissa."},"mid":{"type":"integer","format":"int64","description":"Middle 32 bits of the 96-bit mantissa."},"hi":{"type":"integer","format":"int64","description":"High 32 bits of the 96-bit mantissa."},"flags":{"type":"integer","format":"int64","description":"Flags word:\n - Bits 16–23: scale (0–28)\n - Bit 31: sign (0 = positive, 1 = negative)\n - Other bits must be zero."}},"description":"A fixed-precision decimal number with up to 28 fractional digits.\n\nThis message represents decimal numbers with exact precision, avoiding\nfloating-point rounding errors. It's particularly useful for financial\ncalculations, measurements, and any scenario where exact decimal\nrepresentation is required.\n\nThe value is calculated as: m / 10^e, where:\n - m is an unsigned 96-bit integer composed of (lo, mid, hi)\n - e is the scale (0–28) stored in flags bits 16–23\n - sign is encoded in flags bit 31 (0 = positive, 1 = negative)\n\nExamples:\n - 123.45 would have m=12345, e=2\n - -0.001 would have m=1, e=3, with sign bit set\n"},"typeDate":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Year of the date. Must be from 1 to 9999, or 0 to specify a date without\na year."},"month":{"type":"integer","format":"int32","description":"Month of a year. Must be from 1 to 12, or 0 to specify a year without a\nmonth and day."},"day":{"type":"integer","format":"int32","description":"Day of a month. Must be from 1 to 31 and valid for the year and month, or 0\nto specify a year by itself or a year and month where the day isn't\nsignificant."}},"description":"* A full date, with non-zero year, month, and day values\n* A month and day value, with a zero year, such as an anniversary\n* A year on its own, with zero month and day values\n* A year and month value, with a zero day, such as a credit card expiration\ndate\n\nRelated types are [google.type.TimeOfDay][google.type.TimeOfDay] and\n`google.protobuf.Timestamp`.","title":"Represents a whole or partial calendar date, such as a birthday. The time of\nday and time zone are either specified elsewhere or are insignificant. The\ndate is relative to the Gregorian Calendar. This can represent one of the\nfollowing:"},"typeTimeOfDay":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","description":"Hours of day in 24 hour format. Should be from 0 to 23. An API may choose\nto allow the value \"24:00:00\" for scenarios like business closing time."},"minutes":{"type":"integer","format":"int32","description":"Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Seconds of minutes of the time. Must normally be from 0 to 59. An API may\nallow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Fractions of seconds in nanoseconds. Must be from 0 to 999,999,999."}},"description":"Represents a time of day. The date and time zone are either not significant\nor are specified elsewhere. An API may choose to allow leap seconds. Related\ntypes are [google.type.Date][google.type.Date] and\n`google.protobuf.Timestamp`."},"typeDateTime":{"type":"object","properties":{"year":{"type":"integer","format":"int32","description":"Optional. Year of date. Must be from 1 to 9999, or 0 if specifying a\ndatetime without a year."},"month":{"type":"integer","format":"int32","description":"Required. Month of year. Must be from 1 to 12."},"day":{"type":"integer","format":"int32","description":"Required. Day of month. Must be from 1 to 31 and valid for the year and\nmonth."},"hours":{"type":"integer","format":"int32","description":"Required. Hours of day in 24 hour format. Should be from 0 to 23. An API\nmay choose to allow the value \"24:00:00\" for scenarios like business\nclosing time."},"minutes":{"type":"integer","format":"int32","description":"Required. Minutes of hour of day. Must be from 0 to 59."},"seconds":{"type":"integer","format":"int32","description":"Required. Seconds of minutes of the time. Must normally be from 0 to 59. An\nAPI may allow the value 60 if it allows leap-seconds."},"nanos":{"type":"integer","format":"int32","description":"Required. Fractions of seconds in nanoseconds. Must be from 0 to\n999,999,999."},"utc_offset":{"type":"string","description":"UTC offset. Must be whole seconds, between -18 hours and +18 hours.\nFor example, a UTC offset of -4:00 would be represented as\n{ seconds: -14400 }."},"time_zone":{"$ref":"#/components/schemas/typeTimeZone"}},"description":"Represents civil time (or occasionally physical time).\n\nThis type can represent a civil time in one of a few possible ways:\n\n * When utc_offset is set and time_zone is unset: a civil time on a calendar\n day with a particular offset from UTC.\n * When time_zone is set and utc_offset is unset: a civil time on a calendar\n day in a particular time zone.\n * When neither time_zone nor utc_offset is set: a civil time on a calendar\n day in local time.\n\nThe date is relative to the Proleptic Gregorian Calendar.\n\nIf year is 0, the DateTime is considered not to have a specific year. month\nand day must have valid, non-zero values.\n\nThis type may also be used to represent a physical time if all the date and\ntime fields are set and either case of the `time_offset` oneof is set.\nConsider using `Timestamp` message for physical time instead. If your use\ncase also would like to store the user's timezone, that can be done in\nanother field.\n\nThis type is more flexible than some applications may want. Make sure to\ndocument and validate your application's limitations."},"typeTimeZone":{"type":"object","properties":{"id":{"type":"string","description":"IANA Time Zone Database time zone, e.g. \"America/New_York\"."},"version":{"type":"string","description":"Optional. IANA Time Zone Database version number, e.g. \"2019a\"."}},"description":"Represents a time zone from the\n[IANA Time Zone Database](https://www.iana.org/time-zones)."},"v1List":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/commonV1Value"},"title":"The ordered sequence of values in this list"}},"description":"Represents an ordered collection of values (similar to arrays or lists).\n\nThis message can contain any number of Value elements in a specific order.\nLists are mutable and can grow or shrink during runtime. Elements can be\naccessed by their zero-based index position.\n\nExamples:\n - [1, 2, 3] - list of numbers\n - [\"hello\", \"world\"] - list of strings\n - [true, 42, \"mixed\"] - list with mixed types\n - [[1, 2], [3, 4]] - nested lists"},"v1Dictionary":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryEntry"},"title":"The key-value pairs stored in this dictionary"}},"description":"Represents a key-value mapping (similar to hash maps or dictionaries).\n\nThis message stores associations between keys and values, where keys must be\nhashable types (null, bool, Number, string, Date, TimeOfDay, DateTime, TimeZone). Keys are\nunique within a dictionary - duplicate keys will overwrite previous values.\n\nThe dictionary maintains insertion order for consistent iteration behavior.\n\nExamples:\n - {\"name\": \"John\", \"age\": 30} - string keys with mixed values\n - {1: \"one\", 2: \"two\"} - number keys with string values\n - {\"nested\": {\"inner\": \"value\"}} - nested dictionaries"},"v1DictionaryEntry":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/v1HashableValue"},"value":{"$ref":"#/components/schemas/commonV1Value"}},"description":"Represents a single key-value pair within a Dictionary.\n\nBoth key and value can be any Value type, though keys should be\nhashable types for proper dictionary behavior. Non-hashable keys\n(like lists or dictionaries) may cause runtime errors."},"v1HashableValue":{"type":"object","properties":{"bool_value":{"type":"boolean","title":"Boolean true/false value"},"number":{"$ref":"#/components/schemas/v1Number"},"text":{"type":"string","title":"UTF-8 encoded text string"},"date":{"$ref":"#/components/schemas/typeDate"},"timeofday":{"$ref":"#/components/schemas/typeTimeOfDay"},"datetime":{"$ref":"#/components/schemas/typeDateTime"},"duration":{"type":"string","title":"Signed duration representing a span of time"}},"description":"Represents a hashable value that can be used as a dictionary key.\n\nThis message contains only the hashable types from the Value message,\ncorresponding to Python's hashable types. These types can be safely\nused as keys in maps and dictionaries.\n\nHashable types include: bool, Number, string, Date, TimeOfDay, DateTime\nand Duration."},"v1FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1File"}},"title":"A file value represents a file that can be either inline or remote"},"v1File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v1TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v1Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v1Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v1Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v1Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"}},"name":{"type":"string"}}},"bdkV1Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v1NounPhrase"},"text_value":{"type":"string"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v1Date"},"time_value":{"$ref":"#/components/schemas/v1Time"},"file_value":{"$ref":"#/components/schemas/v1FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v1DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV1ListValue"},"opaque_value":{"$ref":"#/components/schemas/v1OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v1TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v1SensitiveValue"}},"title":"A union of all possible values"},"v1NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v1Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v1Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v1DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v1DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v1DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV1ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV1Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v1OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v1NounPhrase"},"title":"Is a replationships for the opaque"}}},"v1SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV1Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v1Set":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1HashableValue"},"title":"The unique elements stored in this set\nAll elements must be hashable types"}},"description":"Represents an unordered collection of unique values.\n\nThis message stores a collection of unique elements, where duplicate values\nare automatically removed. Only hashable types can be stored in sets.\nSets are useful for membership testing, removing duplicates, and mathematical\nset operations like union, intersection, and difference.\n\nThe set does not maintain insertion order - elements may appear in any order\nduring iteration.\n\nExamples:\n - {1, 2, 3} - set of numbers\n - {\"apple\", \"banana\", \"cherry\"} - set of strings\n - {true, false} - set of booleans\n - {1, \"hello\", true} - set with mixed hashable types"},"v1ExecutableStep":{"type":"object","properties":{"code":{"type":"string","description":"The source code to be executed, written in SPy (Simplified Python) language.\nThis is the main logic that will be interpreted and run by the execution engine."},"book_connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"description":"Book connections required by this executable.\nMaps connection names to their specific ID and endpoints."},"phase_type":{"$ref":"#/components/schemas/v1AutomationPhaseType"}},"description":"ExecutableStep represents a piece of code that can be executed in the Jeeves platform.\nContains the source code, input parameters, and external dependencies needed for execution.","required":["code","phase_type"]},"v1BookConnection":{"type":"object","properties":{"connection_id":{"type":"string","description":"Unique identifier for this connection resource."},"endpoint":{"type":"string","description":"Endpoint for the connection."}},"description":"BookConnection is a resource representing a connection to a book instance.\nA connection has a unique identifier and an endpoint."},"v1AutomationPhaseType":{"type":"string","enum":["AUTOMATION_PHASE_TYPE_UNSPECIFIED","AUTOMATION_PHASE_TYPE_PRE","AUTOMATION_PHASE_TYPE_MAIN","AUTOMATION_PHASE_TYPE_POST"],"default":"AUTOMATION_PHASE_TYPE_UNSPECIFIED","description":"PhaseType defines the type of phase for an automation trigger.\n\n - AUTOMATION_PHASE_TYPE_UNSPECIFIED: Unspecified phase type.\n - AUTOMATION_PHASE_TYPE_PRE: Pre-processing phase.\n - AUTOMATION_PHASE_TYPE_MAIN: Main processing phase.\n - AUTOMATION_PHASE_TYPE_POST: Post-processing phase."},"v1RunState":{"type":"object","properties":{"pending":{"$ref":"#/components/schemas/v1PendingRunState"},"executing":{"$ref":"#/components/schemas/v1ExecutingRunState"},"stopping":{"$ref":"#/components/schemas/v1StoppingRunState"},"stopped":{"$ref":"#/components/schemas/v1StoppedRunState"},"awaiting_guidance":{"$ref":"#/components/schemas/v1AwaitingGuidanceRunState"},"completed":{"$ref":"#/components/schemas/v1CompletedRunState"},"failed":{"$ref":"#/components/schemas/v1FailedRunState"},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the run transitioned to this state.","readOnly":true}},"description":"RunState represents the overall lifecycle state of a run.\nTracks the run from initial submission through completion or failure."},"v1PendingRunState":{"type":"object","description":"Run has been submitted and is waiting to start execution.\nThe run is queued and will begin when resources become available."},"v1ExecutingRunState":{"type":"object","description":"Run is currently being executed.\nCode is actively running and making progress."},"v1StoppingRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run is in the process of being stopped.\nExecution is stopping gracefully and will transition to STOPPED state."},"v1StoppedRunState":{"type":"object","properties":{"reason":{"type":"string","description":"The reason provided by the user for stopping the run.","readOnly":true}},"description":"Run has been stopped and can be resumed later.\nExecution is temporarily stopped but can continue from current state."},"v1AwaitingGuidanceRunState":{"type":"object","properties":{"exception":{"type":"string","title":"ID of the exception (from guidance center)","readOnly":true},"description":{"type":"string","description":"Description of the exception that occured.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run is waiting for external guidance or user input.\nRequires manual intervention or external decision to proceed."},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1CompletedRunState":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The outputs of the run.","readOnly":true}},"description":"Run has completed successfully.\nAll code has been executed and results are available."},"v1FailedRunState":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the error that caused the run to fail.","readOnly":true},"description":{"type":"string","description":"The description of the error.","readOnly":true},"location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"Run has failed due to an error.\nExecution stopped due to an unrecoverable error condition."},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"v1InvocationDetails":{"type":"object","properties":{"trigger_id":{"type":"string","description":"The ID of the trigger that initiated this run, if applicable."},"user_id":{"type":"string","description":"The ID of the user that initiated this run, if applicable."},"invocation_source":{"$ref":"#/components/schemas/v1InvocationSource"}},"description":"InvocationDetails contains additional information about the entity that initiated a run."},"v1InvocationSource":{"type":"string","enum":["INVOCATION_SOURCE_UNSPECIFIED","INVOCATION_SOURCE_MANUAL","INVOCATION_SOURCE_TRIGGER","INVOCATION_SOURCE_SCHEDULE"],"default":"INVOCATION_SOURCE_UNSPECIFIED","description":"InvocationSource identifies the entity responsible for creating a run.\n\n - INVOCATION_SOURCE_UNSPECIFIED: Unspecified invocation source.\n - INVOCATION_SOURCE_MANUAL: Run was manually initiated by a user.\n - INVOCATION_SOURCE_TRIGGER: Run was triggered by an event or trigger.\n - INVOCATION_SOURCE_SCHEDULE: Run was initiated by a schedule."},"v1ExecutionJournal":{"type":"object","properties":{"execution_id":{"type":"string","title":"Unique identifier for the execution"},"run_id":{"type":"string","title":"Optional: Run identifier, set if the execution is part of a run"},"event_time":{"type":"string","format":"date-time","title":"When this journal entry was generated"},"started":{"$ref":"#/components/schemas/v1ExecutionStarted"},"completed":{"$ref":"#/components/schemas/v1ExecutionCompleted"},"stopped":{"$ref":"#/components/schemas/v1ExecutionStopped"},"failed":{"$ref":"#/components/schemas/v1ExecutionFailed"},"node_started":{"$ref":"#/components/schemas/v1NodeStarted"},"node_executed":{"$ref":"#/components/schemas/v1NodeExecuted"},"node_skipped":{"$ref":"#/components/schemas/v1NodeSkipped"},"node_patched":{"$ref":"#/components/schemas/v1NodePatched"},"patched_node_started":{"$ref":"#/components/schemas/v1PatchedNodeStarted"},"patched_node_executed":{"$ref":"#/components/schemas/v1PatchedNodeExecuted"},"automation_id":{"type":"string","title":"Optional: Automation identifier, set if the execution is part of an automation"},"automation_phase_id":{"type":"string","title":"Optional: Automation phase identifier, set if the execution is part of an automation phase"},"code_hash":{"type":"string","title":"Optional: MD5 hash of the SPy code being executed"},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"workspace_id":{"type":"string","title":"The workspace id for which the execution is requested"},"organization_id":{"type":"string","title":"The organization id for which the execution is requested"},"extra_metadata":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Optional extra metadata to be stored with the execution\nThis will be used to pass the additional information that downstream services might require\nbut there is no need to Jarvis to know about it."}},"title":"Journal event for an execution, capturing status and node-level events"},"v1ExecutionStarted":{"type":"object","description":"ExecutionStarted indicates that Jarvis has started the execution."},"v1ExecutionCompleted":{"type":"object","properties":{"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"Map of named output values set by the set_output() builtin function during execution.\nEach entry is a name-value pair where the key is the output name (string) and\nthe value is the output value set by calling set_output(name, value).\nThis map will be empty if no set_output() calls were made during execution."}},"description":"ExecutionCompleted indicates that Jarvis has successfully completed the execution.\nThe final result value is included in this message, representing the return value of\nthe executed code."},"v1ExecutionStopped":{"type":"object","properties":{"user_stopped":{"$ref":"#/components/schemas/v1UserStopped"},"waiting_on_book":{"$ref":"#/components/schemas/v1WaitingOnBook"},"waiting_on_timer":{"$ref":"#/components/schemas/v1WaitingOnTimer"},"program_stopped":{"$ref":"#/components/schemas/v1ProgramStopped"}},"description":"ExecutionStopped indicates that the execution was stopped before completion due to\na specific reason."},"v1UserStopped":{"type":"object","description":"UserStopped indicates that the execution was stopped by a user."},"v1WaitingOnBook":{"type":"object","description":"WaitingOnBook indicates that the execution is stopped because its\nwaiting on an async book procedure to complete. The run manager is expected\nto resume the execution when the book procedure completes."},"v1WaitingOnTimer":{"type":"object","properties":{"duration":{"type":"string","description":"The duration of the timer."}},"description":"WaitingOnTimer indicates that the execution is stopped because its\nwaiting for a timer to fire. The run manager is expected to resume the\nexecution when the timer fires."},"v1ProgramStopped":{"type":"object","properties":{"reason":{"type":"string","description":"The reason the program was stopped."}},"description":"ProgramStopped indicates that the execution was stopped by the program."},"v1ExecutionFailed":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/v1ExecutionError"}},"description":"ExecutionFailed indicates that the execution encountered an error and\ncould not complete successfully."},"v1ExecutionError":{"type":"object","properties":{"id":{"type":"string","title":"Unique identifier for the error"},"description":{"type":"string","title":"Human-readable description of what went wrong"},"context":{"$ref":"#/components/schemas/v1Context"},"extra":{"type":"object","additionalProperties":{"type":"string"},"title":"Extra information about the error"},"code":{"type":"string","title":"The code where the error was raised (includes patches)\nIf the error was raised in a patch, the code reflects the patched code\nand the error location is relative to the patched code instead of the original\ncode\nNote: this field does not include previous patches that executed successfully"}},"description":"ExecutionError represents an error that occurred during execution."},"v1Context":{"type":"object","properties":{"code_location":{"$ref":"#/components/schemas/commonV1Location"},"node_id":{"type":"string","title":"The id of node"}},"description":"Context provides additional information about the execution environment,\nsuch as stack traces for debugging purposes."},"v1NodeStarted":{"type":"object","properties":{"code_location":{"$ref":"#/components/schemas/commonV1Location"},"node_id":{"type":"string","title":"The id of the node that was started"},"node_kind":{"type":"string","title":"The kind/type of the node that was started"}},"title":"Event emitted when Jarvis begins executing an AST node"},"v1NodeExecuted":{"type":"object","properties":{"code_location":{"$ref":"#/components/schemas/commonV1Location"},"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The input variables & their values\nA variable is defined as an input if it was fetched\nfrom the memory while executing the node or one of its\nchildren."},"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The output variables & their values\nA variable is defined as an output if it was written to\nthe memory while executing the node or one of its\nchildren.\nIf a variable was written multiple times, only the last\nwritten value is considered as the output."},"error":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutionError"},"description":"The list of all the errors that occurred while executing the\nnode or any of its children."},"node_id":{"type":"string","title":"The id of the node that got executed"},"book_function_call":{"$ref":"#/components/schemas/v1BookFunctionCall"},"node_kind":{"type":"string","title":"The kind/type of the node that was executed"}},"title":"Event emitted after Jarvis finishes executing an AST node, with I/O and errors"},"v1BookFunctionCall":{"type":"object","properties":{"book_function":{"$ref":"#/components/schemas/v1BookFunction"},"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"title":"The input variables and their values passed to the book function"},"output":{"$ref":"#/components/schemas/commonV1Value"}},"description":"BookFunctionCall represents a call to an external book function with its inputs and outputs."},"v1BookFunction":{"type":"object","properties":{"connection_spy_identifier":{"type":"string","title":"The connection name for the book instance in the spy code"},"book_name":{"type":"string","title":"The name of the target book containing the function"},"function_name":{"type":"string","title":"The name of the specific function to invoke within the book"},"code_location":{"$ref":"#/components/schemas/commonV1Location"}},"description":"BookFunction represents a reference to an external book function."},"v1NodeSkipped":{"type":"object","properties":{"code_location":{"$ref":"#/components/schemas/commonV1Location"},"node_id":{"type":"string","title":"The id of the node that was skipped"},"node_kind":{"type":"string","title":"The kind/type of the node that was skipped"}},"title":"Event emitted when Jarvis skips executing an AST node"},"v1NodePatched":{"type":"object","properties":{"code_location":{"$ref":"#/components/schemas/commonV1Location"},"code_patch":{"type":"string","title":"The patch SPy code that was applied"},"inputs_patch":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"title":"The execution inputs that were patched"},"connections":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v1BookConnection"},"title":"The book connections that were patched\nThe key is the name of the connection used in the SPy code\nThe value contains the connection details"},"node_id":{"type":"string","title":"The id of the node"},"node_kind":{"type":"string","title":"The kind/type of the node that was patched"}},"title":"Event emitted when a patch is applied to an AST node"},"v1PatchedNodeStarted":{"type":"object","properties":{"patch_location":{"$ref":"#/components/schemas/commonV1Location"},"node_location":{"$ref":"#/components/schemas/commonV1Location"},"node_id":{"type":"string","title":"The id of the patched node for which execution is starting"},"node_kind":{"type":"string","title":"The kind/type of the patched node that is being started"}},"title":"Event emitted when Jarvis starts executing a node inside a patch"},"v1PatchedNodeExecuted":{"type":"object","properties":{"patch_location":{"$ref":"#/components/schemas/commonV1Location"},"node_location":{"$ref":"#/components/schemas/commonV1Location"},"inputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The input variables & their values\nA variable is defined as an input if it was fetched\nfrom the memory while executing the node or one of its\nchildren."},"outputs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/commonV1Value"},"description":"The output variables & their values\nA variable is defined as an output if it was written to\nthe memory while executing the node or one of its\nchildren.\nIf a variable was written multiple times, only the last\nwritten value is considered as the output."},"error":{"type":"array","items":{"$ref":"#/components/schemas/v1ExecutionError"},"description":"The list of all the errors that occurred while executing the\nnode or any of its children."},"node_id":{"type":"string","title":"The id of the patched node for which execution is completed"},"book_function_call":{"$ref":"#/components/schemas/v1BookFunctionCall"},"node_kind":{"type":"string","title":"The kind/type of the patched node that was executed"}},"title":"Event emitted after executing a node inside a patch, with I/O and errors"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/events":{"get":{"summary":"List Run Events","description":"This RPC retrieves a paginated list of all events that occurred during\na specific automation run. Events are returned in the order they were\ngenerated, providing a complete timeline of the run's execution.\n\nUse the filter parameter to narrow results by specific criteria such as\nnode_kind for execution journal events.\n\nThe response includes both high-level run state changes (starts, completions,\nfailures) and detailed execution steps (node executions, execution patches,\ndetailed data flows in each expression, etc).","operationId":"ListRunEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListRunEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"Maximum number of run events to return in a single response.\n\nThe service may return fewer events than requested, but will never\nreturn more. This can happen when:\n- The run has fewer total events than requested\n- Internal chunking limits are reached\n- The remaining events don't fit in the response size limit\n\nValid range: 1-1000 events\nDefault: 100 events if unspecified\nValues above 1000 are automatically capped at 1000\nNegative values result in an INVALID_ARGUMENT error","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Pagination token from a previous ListRunEvents response.\n\nProvide the `next_page_token` value from a previous response to\ncontinue retrieving the next set of events. Leave empty or unset\nfor the first page of results.\n\nThe token is opaque and should not be parsed or modified by clients.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"Filter expression to narrow down which events are returned.\n\nThe filter string follows the AIP-160 filtering syntax\n(https://google.aip.dev/160).\n\nSupported fields for filtering:\n- node_kind: Filter execution journal events by the kind/type of node.\n Only execution journal events with matching node_kind are returned.\n Example: node_kind = \"FunctionCall\"\n\nWhen empty or unset, all events for the specified run are returned.\n\nExample filters:\n node_kind = \"FunctionCall\"\n node_kind = \"Assignment\"","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Runs"]}}}} ``` # Books Browse and search books, concepts, procedures, connections, and triggers. ## View Books > This endpoint returns metadata for all books that are currently available\ > in the runtime, including their names, versions, descriptions, authentication\ > requirements, and capabilities. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBooksResponse":{"type":"object","properties":{"books":{"type":"array","items":{"$ref":"#/components/schemas/v2BookDescriptor"},"title":"All the books that satisfy the query"},"next_page_token":{"type":"string","description":"The token to use to retrieve the next page of books."}}},"v2BookDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"@deprecated, use name and version to uniquely identify a book","title":"The identifier of the book (a.k.a integration_id)"},"name":{"type":"string","title":"The name of the book"},"short_description":{"type":"string","title":"Short description of the book"},"long_description":{"type":"string","title":"Short description of the book"},"author":{"type":"string","title":"Author of the book"},"icon":{"type":"string","format":"byte","title":"Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP)"},"version":{"type":"string","title":"Version of the book"},"authentications":{"type":"array","items":{"$ref":"#/components/schemas/v2BookAuthenticationDescriptor"},"title":"Authentication mechanism for a book version"},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book. Note: replaced by config_map"},"display_name":{"type":"string","title":"Display name of the book"},"endpoint":{"type":"string","title":"URI location of the book, such as lambda://microsoft/1.0.4"},"connection_required":{"type":"boolean","description":"Connection Required. True if all procedures always require a connection."},"discover_capable":{"type":"boolean","title":"True if the book is capable of discovering book procedures"},"tags":{"type":"array","items":{"type":"string"},"title":"Tags associated with the book"},"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Book procedures"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"userinfo_capable":{"type":"boolean","title":"True if the book is capable of returning oauth user's info"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/v2BookTriggerDescriptor"},"title":"Book triggers"},"bdk_runtime_version":{"type":"string","title":"BDK Runtime version"},"environment_information":{"$ref":"#/components/schemas/bdkV2EnvironmentInformation"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book"},"hidden":{"type":"boolean","title":"True if the book is hidden"},"polls":{"type":"array","items":{"$ref":"#/components/schemas/v2BookPollDescriptor"},"title":"Book polls"}}},"v2BookAuthenticationDescriptor":{"type":"object","properties":{"custom":{"$ref":"#/components/schemas/v2BookCustomAuthenticationDescriptor"},"oauth":{"$ref":"#/components/schemas/v2BookOAuthAuthenticationDescriptor"}}},"v2BookCustomAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credentials required to perform authentication"},"description":{"type":"string","title":"A description of the authentication"},"name":{"type":"string","title":"A name for the authentication"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2CredentialDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"type":{"$ref":"#/components/schemas/v2CredentialType"},"label":{"type":"string","title":"Label that will be displayed to the user during configuration of the book"},"visible":{"type":"boolean","description":"True if the value is visible to the book, false otherwise."},"description":{"type":"string","title":"Description"}}},"v2CredentialType":{"type":"string","enum":["CredentialTypeText","CredentialTypeSensitiveText"],"default":"CredentialTypeText","title":"Supported configuration types"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2BookOAuthAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"provider":{"$ref":"#/components/schemas/v2OAuthProvider"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthFlow"},"title":"Supported OAuth flows"},"authorize_endpoint":{"type":"string","title":"Authorize endpoint"},"token_endpoint":{"type":"string","title":"Token endpoint"},"scope":{"type":"array","items":{"type":"string"},"title":"Scopes"},"name":{"type":"string","title":"A name for the authentication"},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthArgumentDescriptor"},"title":"Additional arguments which are not part of the OAuth specification\nbut are required for the authentication to work (such as tenant_id)"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credential descriptors"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2OAuthProvider":{"type":"string","enum":["OAuthProviderMicrosoft","OAuthProviderGoogle","OAuthProviderGeneric"],"default":"OAuthProviderMicrosoft","title":"Supported OAuth providers"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"},"v2OAuthArgumentDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the parameter"},"name":{"type":"string","title":"Name of the parameter"},"description":{"type":"string","title":"Description of the parameter"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2BookTriggerDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger"},"name":{"type":"string","title":"The name of the trigger"},"description":{"type":"string","title":"Description of the trigger"},"setup_description":{"type":"string","title":"Setup description for the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the trigger"},"filter_capable":{"type":"boolean","title":"True if the trigger is capable of filtering events"},"is_manual":{"type":"boolean","title":"True if the trigger is manually invoked"},"event_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Event type schema for the trigger"},"is_shared_endpoint":{"type":"boolean","description":"True if every trigger instance of this trigger shares the same endpoint when configured."}}},"bdkV2EnvironmentInformation":{"type":"object","properties":{"version":{"type":"string"},"runtime_name":{"type":"string","title":"Runtime name"},"runtime_version":{"type":"string","title":"Runtime version"},"bci_protocol_version":{"type":"string","title":"BCI Protocol version"},"api_version":{"type":"string","title":"BDK API Version"},"path":{"type":"array","items":{"type":"string"},"title":"Book path under which books will be discovered"}},"title":"Information about the environment"},"v2BookPollDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the poll"},"name":{"type":"string","title":"The name of the poll"},"description":{"type":"string","title":"Description of the poll"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the poll"},"stop_function_name":{"type":"string","title":"Required stop function name"},"output_concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/books":{"get":{"summary":"View Books","description":"This endpoint returns metadata for all books that are currently available\nin the runtime, including their names, versions, descriptions, authentication\nrequirements, and capabilities.","operationId":"ListBooks","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBooksResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"page_size","description":"The maximum number of books to return.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The token to use to retrieve the next page of books.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"AIP-160 Filter expression\nhttps://google.aip.dev/160","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Book Details > This endpoint provides comprehensive metadata about a particular book,\ > including its description, author, icon, authentication mechanisms,\ > configuration parameters, and capabilities. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookResponse":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/v2BookDescriptor"}}},"v2BookDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"@deprecated, use name and version to uniquely identify a book","title":"The identifier of the book (a.k.a integration_id)"},"name":{"type":"string","title":"The name of the book"},"short_description":{"type":"string","title":"Short description of the book"},"long_description":{"type":"string","title":"Short description of the book"},"author":{"type":"string","title":"Author of the book"},"icon":{"type":"string","format":"byte","title":"Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP)"},"version":{"type":"string","title":"Version of the book"},"authentications":{"type":"array","items":{"$ref":"#/components/schemas/v2BookAuthenticationDescriptor"},"title":"Authentication mechanism for a book version"},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book. Note: replaced by config_map"},"display_name":{"type":"string","title":"Display name of the book"},"endpoint":{"type":"string","title":"URI location of the book, such as lambda://microsoft/1.0.4"},"connection_required":{"type":"boolean","description":"Connection Required. True if all procedures always require a connection."},"discover_capable":{"type":"boolean","title":"True if the book is capable of discovering book procedures"},"tags":{"type":"array","items":{"type":"string"},"title":"Tags associated with the book"},"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Book procedures"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"userinfo_capable":{"type":"boolean","title":"True if the book is capable of returning oauth user's info"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/v2BookTriggerDescriptor"},"title":"Book triggers"},"bdk_runtime_version":{"type":"string","title":"BDK Runtime version"},"environment_information":{"$ref":"#/components/schemas/bdkV2EnvironmentInformation"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book"},"hidden":{"type":"boolean","title":"True if the book is hidden"},"polls":{"type":"array","items":{"$ref":"#/components/schemas/v2BookPollDescriptor"},"title":"Book polls"}}},"v2BookAuthenticationDescriptor":{"type":"object","properties":{"custom":{"$ref":"#/components/schemas/v2BookCustomAuthenticationDescriptor"},"oauth":{"$ref":"#/components/schemas/v2BookOAuthAuthenticationDescriptor"}}},"v2BookCustomAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credentials required to perform authentication"},"description":{"type":"string","title":"A description of the authentication"},"name":{"type":"string","title":"A name for the authentication"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2CredentialDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"type":{"$ref":"#/components/schemas/v2CredentialType"},"label":{"type":"string","title":"Label that will be displayed to the user during configuration of the book"},"visible":{"type":"boolean","description":"True if the value is visible to the book, false otherwise."},"description":{"type":"string","title":"Description"}}},"v2CredentialType":{"type":"string","enum":["CredentialTypeText","CredentialTypeSensitiveText"],"default":"CredentialTypeText","title":"Supported configuration types"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2BookOAuthAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"provider":{"$ref":"#/components/schemas/v2OAuthProvider"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthFlow"},"title":"Supported OAuth flows"},"authorize_endpoint":{"type":"string","title":"Authorize endpoint"},"token_endpoint":{"type":"string","title":"Token endpoint"},"scope":{"type":"array","items":{"type":"string"},"title":"Scopes"},"name":{"type":"string","title":"A name for the authentication"},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthArgumentDescriptor"},"title":"Additional arguments which are not part of the OAuth specification\nbut are required for the authentication to work (such as tenant_id)"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credential descriptors"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2OAuthProvider":{"type":"string","enum":["OAuthProviderMicrosoft","OAuthProviderGoogle","OAuthProviderGeneric"],"default":"OAuthProviderMicrosoft","title":"Supported OAuth providers"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"},"v2OAuthArgumentDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the parameter"},"name":{"type":"string","title":"Name of the parameter"},"description":{"type":"string","title":"Description of the parameter"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2BookTriggerDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger"},"name":{"type":"string","title":"The name of the trigger"},"description":{"type":"string","title":"Description of the trigger"},"setup_description":{"type":"string","title":"Setup description for the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the trigger"},"filter_capable":{"type":"boolean","title":"True if the trigger is capable of filtering events"},"is_manual":{"type":"boolean","title":"True if the trigger is manually invoked"},"event_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Event type schema for the trigger"},"is_shared_endpoint":{"type":"boolean","description":"True if every trigger instance of this trigger shares the same endpoint when configured."}}},"bdkV2EnvironmentInformation":{"type":"object","properties":{"version":{"type":"string"},"runtime_name":{"type":"string","title":"Runtime name"},"runtime_version":{"type":"string","title":"Runtime version"},"bci_protocol_version":{"type":"string","title":"BCI Protocol version"},"api_version":{"type":"string","title":"BDK API Version"},"path":{"type":"array","items":{"type":"string"},"title":"Book path under which books will be discovered"}},"title":"Information about the environment"},"v2BookPollDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the poll"},"name":{"type":"string","title":"The name of the poll"},"description":{"type":"string","title":"Description of the poll"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the poll"},"stop_function_name":{"type":"string","title":"Required stop function name"},"output_concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/books/{name}/{version}":{"get":{"summary":"View Book Details","description":"This endpoint provides comprehensive metadata about a particular book,\nincluding its description, author, icon, authentication mechanisms,\nconfiguration parameters, and capabilities.","operationId":"GetBook","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Book Procedures > This endpoint returns a list of all procedures (functions/operations) that\ > can be invoked on the specified book, along with their signatures, input/output\ > parameters, and metadata such as descriptions and examples. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookProceduresResponse":{"type":"object","properties":{"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Available procedures"}},"title":"Retrieve all the available signatures for a book"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/books/{name}/{version}/procedures":{"get":{"summary":"View Book Procedures","description":"This endpoint returns a list of all procedures (functions/operations) that\ncan be invoked on the specified book, along with their signatures, input/output\nparameters, and metadata such as descriptions and examples.","operationId":"ListBookProcedures","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Tags > This endpoint returns a consolidated list of all tags used across all books\ > in the library. Tags are used for categorizing and organizing books by\ > functionality, domain, or other characteristics. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveTagsResponse":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"title":"Tags"}},"title":"Response to retrieve tags"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/tags":{"get":{"summary":"View Tags","description":"This endpoint returns a consolidated list of all tags used across all books\nin the library. Tags are used for categorizing and organizing books by\nfunctionality, domain, or other characteristics.","operationId":"ListTags","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveTagsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"tags":["Books"]}}}} ``` ## View Latest Books > This endpoint returns metadata for all books that are currently available\ > in the runtime, including their names, versions, descriptions, authentication\ > requirements, and capabilities. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBooksResponse":{"type":"object","properties":{"books":{"type":"array","items":{"$ref":"#/components/schemas/v2BookDescriptor"},"title":"All the books that satisfy the query"},"next_page_token":{"type":"string","description":"The token to use to retrieve the next page of books."}}},"v2BookDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"@deprecated, use name and version to uniquely identify a book","title":"The identifier of the book (a.k.a integration_id)"},"name":{"type":"string","title":"The name of the book"},"short_description":{"type":"string","title":"Short description of the book"},"long_description":{"type":"string","title":"Short description of the book"},"author":{"type":"string","title":"Author of the book"},"icon":{"type":"string","format":"byte","title":"Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP)"},"version":{"type":"string","title":"Version of the book"},"authentications":{"type":"array","items":{"$ref":"#/components/schemas/v2BookAuthenticationDescriptor"},"title":"Authentication mechanism for a book version"},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book. Note: replaced by config_map"},"display_name":{"type":"string","title":"Display name of the book"},"endpoint":{"type":"string","title":"URI location of the book, such as lambda://microsoft/1.0.4"},"connection_required":{"type":"boolean","description":"Connection Required. True if all procedures always require a connection."},"discover_capable":{"type":"boolean","title":"True if the book is capable of discovering book procedures"},"tags":{"type":"array","items":{"type":"string"},"title":"Tags associated with the book"},"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Book procedures"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"userinfo_capable":{"type":"boolean","title":"True if the book is capable of returning oauth user's info"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/v2BookTriggerDescriptor"},"title":"Book triggers"},"bdk_runtime_version":{"type":"string","title":"BDK Runtime version"},"environment_information":{"$ref":"#/components/schemas/bdkV2EnvironmentInformation"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book"},"hidden":{"type":"boolean","title":"True if the book is hidden"},"polls":{"type":"array","items":{"$ref":"#/components/schemas/v2BookPollDescriptor"},"title":"Book polls"}}},"v2BookAuthenticationDescriptor":{"type":"object","properties":{"custom":{"$ref":"#/components/schemas/v2BookCustomAuthenticationDescriptor"},"oauth":{"$ref":"#/components/schemas/v2BookOAuthAuthenticationDescriptor"}}},"v2BookCustomAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credentials required to perform authentication"},"description":{"type":"string","title":"A description of the authentication"},"name":{"type":"string","title":"A name for the authentication"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2CredentialDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"type":{"$ref":"#/components/schemas/v2CredentialType"},"label":{"type":"string","title":"Label that will be displayed to the user during configuration of the book"},"visible":{"type":"boolean","description":"True if the value is visible to the book, false otherwise."},"description":{"type":"string","title":"Description"}}},"v2CredentialType":{"type":"string","enum":["CredentialTypeText","CredentialTypeSensitiveText"],"default":"CredentialTypeText","title":"Supported configuration types"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2BookOAuthAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"provider":{"$ref":"#/components/schemas/v2OAuthProvider"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthFlow"},"title":"Supported OAuth flows"},"authorize_endpoint":{"type":"string","title":"Authorize endpoint"},"token_endpoint":{"type":"string","title":"Token endpoint"},"scope":{"type":"array","items":{"type":"string"},"title":"Scopes"},"name":{"type":"string","title":"A name for the authentication"},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthArgumentDescriptor"},"title":"Additional arguments which are not part of the OAuth specification\nbut are required for the authentication to work (such as tenant_id)"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credential descriptors"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2OAuthProvider":{"type":"string","enum":["OAuthProviderMicrosoft","OAuthProviderGoogle","OAuthProviderGeneric"],"default":"OAuthProviderMicrosoft","title":"Supported OAuth providers"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"},"v2OAuthArgumentDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the parameter"},"name":{"type":"string","title":"Name of the parameter"},"description":{"type":"string","title":"Description of the parameter"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2BookTriggerDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger"},"name":{"type":"string","title":"The name of the trigger"},"description":{"type":"string","title":"Description of the trigger"},"setup_description":{"type":"string","title":"Setup description for the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the trigger"},"filter_capable":{"type":"boolean","title":"True if the trigger is capable of filtering events"},"is_manual":{"type":"boolean","title":"True if the trigger is manually invoked"},"event_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Event type schema for the trigger"},"is_shared_endpoint":{"type":"boolean","description":"True if every trigger instance of this trigger shares the same endpoint when configured."}}},"bdkV2EnvironmentInformation":{"type":"object","properties":{"version":{"type":"string"},"runtime_name":{"type":"string","title":"Runtime name"},"runtime_version":{"type":"string","title":"Runtime version"},"bci_protocol_version":{"type":"string","title":"BCI Protocol version"},"api_version":{"type":"string","title":"BDK API Version"},"path":{"type":"array","items":{"type":"string"},"title":"Book path under which books will be discovered"}},"title":"Information about the environment"},"v2BookPollDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the poll"},"name":{"type":"string","title":"The name of the poll"},"description":{"type":"string","title":"Description of the poll"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the poll"},"stop_function_name":{"type":"string","title":"Required stop function name"},"output_concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/books:latest":{"get":{"summary":"View Latest Books","description":"This endpoint returns metadata for all books that are currently available\nin the runtime, including their names, versions, descriptions, authentication\nrequirements, and capabilities.","operationId":"ListLatestBooks","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBooksResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"page_size","description":"The maximum number of books to return.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The token to use to retrieve the next page of books.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"AIP-160 Filter expression\nhttps://google.aip.dev/160","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Book Versions > This endpoint returns a list of all version strings available for the\ > specified book name. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookVersionsResponse":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"string"},"title":"All available versions for the specified book"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/books/{name}/versions":{"get":{"summary":"View Book Versions","description":"This endpoint returns a list of all version strings available for the\nspecified book name.","operationId":"ListBookVersions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookVersionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Book Concepts > This endpoint returns a list of concept descriptors defined by the\ > specified book, which can be referenced by procedures as inputs or outputs. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookConceptsResponse":{"type":"object","properties":{"concepts":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Available concepts"}},"title":"Retrieve all the available concept descriptors for a book"},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/books/{name}/{version}/concepts":{"get":{"summary":"View Book Concepts","description":"This endpoint returns a list of concept descriptors defined by the\nspecified book, which can be referenced by procedures as inputs or outputs.","operationId":"ListBookConcepts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookConceptsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Workspace Books > This endpoint returns metadata for all books that are currently available\ > in the runtime for the specified workspace, including their names, versions,\ > descriptions, authentication requirements, and capabilities. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBooksResponse":{"type":"object","properties":{"books":{"type":"array","items":{"$ref":"#/components/schemas/v2BookDescriptor"},"title":"All the books that satisfy the query"},"next_page_token":{"type":"string","description":"The token to use to retrieve the next page of books."}}},"v2BookDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"@deprecated, use name and version to uniquely identify a book","title":"The identifier of the book (a.k.a integration_id)"},"name":{"type":"string","title":"The name of the book"},"short_description":{"type":"string","title":"Short description of the book"},"long_description":{"type":"string","title":"Short description of the book"},"author":{"type":"string","title":"Author of the book"},"icon":{"type":"string","format":"byte","title":"Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP)"},"version":{"type":"string","title":"Version of the book"},"authentications":{"type":"array","items":{"$ref":"#/components/schemas/v2BookAuthenticationDescriptor"},"title":"Authentication mechanism for a book version"},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book. Note: replaced by config_map"},"display_name":{"type":"string","title":"Display name of the book"},"endpoint":{"type":"string","title":"URI location of the book, such as lambda://microsoft/1.0.4"},"connection_required":{"type":"boolean","description":"Connection Required. True if all procedures always require a connection."},"discover_capable":{"type":"boolean","title":"True if the book is capable of discovering book procedures"},"tags":{"type":"array","items":{"type":"string"},"title":"Tags associated with the book"},"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Book procedures"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"userinfo_capable":{"type":"boolean","title":"True if the book is capable of returning oauth user's info"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/v2BookTriggerDescriptor"},"title":"Book triggers"},"bdk_runtime_version":{"type":"string","title":"BDK Runtime version"},"environment_information":{"$ref":"#/components/schemas/bdkV2EnvironmentInformation"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book"},"hidden":{"type":"boolean","title":"True if the book is hidden"},"polls":{"type":"array","items":{"$ref":"#/components/schemas/v2BookPollDescriptor"},"title":"Book polls"}}},"v2BookAuthenticationDescriptor":{"type":"object","properties":{"custom":{"$ref":"#/components/schemas/v2BookCustomAuthenticationDescriptor"},"oauth":{"$ref":"#/components/schemas/v2BookOAuthAuthenticationDescriptor"}}},"v2BookCustomAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credentials required to perform authentication"},"description":{"type":"string","title":"A description of the authentication"},"name":{"type":"string","title":"A name for the authentication"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2CredentialDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"type":{"$ref":"#/components/schemas/v2CredentialType"},"label":{"type":"string","title":"Label that will be displayed to the user during configuration of the book"},"visible":{"type":"boolean","description":"True if the value is visible to the book, false otherwise."},"description":{"type":"string","title":"Description"}}},"v2CredentialType":{"type":"string","enum":["CredentialTypeText","CredentialTypeSensitiveText"],"default":"CredentialTypeText","title":"Supported configuration types"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2BookOAuthAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"provider":{"$ref":"#/components/schemas/v2OAuthProvider"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthFlow"},"title":"Supported OAuth flows"},"authorize_endpoint":{"type":"string","title":"Authorize endpoint"},"token_endpoint":{"type":"string","title":"Token endpoint"},"scope":{"type":"array","items":{"type":"string"},"title":"Scopes"},"name":{"type":"string","title":"A name for the authentication"},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthArgumentDescriptor"},"title":"Additional arguments which are not part of the OAuth specification\nbut are required for the authentication to work (such as tenant_id)"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credential descriptors"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2OAuthProvider":{"type":"string","enum":["OAuthProviderMicrosoft","OAuthProviderGoogle","OAuthProviderGeneric"],"default":"OAuthProviderMicrosoft","title":"Supported OAuth providers"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"},"v2OAuthArgumentDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the parameter"},"name":{"type":"string","title":"Name of the parameter"},"description":{"type":"string","title":"Description of the parameter"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2BookTriggerDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger"},"name":{"type":"string","title":"The name of the trigger"},"description":{"type":"string","title":"Description of the trigger"},"setup_description":{"type":"string","title":"Setup description for the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the trigger"},"filter_capable":{"type":"boolean","title":"True if the trigger is capable of filtering events"},"is_manual":{"type":"boolean","title":"True if the trigger is manually invoked"},"event_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Event type schema for the trigger"},"is_shared_endpoint":{"type":"boolean","description":"True if every trigger instance of this trigger shares the same endpoint when configured."}}},"bdkV2EnvironmentInformation":{"type":"object","properties":{"version":{"type":"string"},"runtime_name":{"type":"string","title":"Runtime name"},"runtime_version":{"type":"string","title":"Runtime version"},"bci_protocol_version":{"type":"string","title":"BCI Protocol version"},"api_version":{"type":"string","title":"BDK API Version"},"path":{"type":"array","items":{"type":"string"},"title":"Book path under which books will be discovered"}},"title":"Information about the environment"},"v2BookPollDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the poll"},"name":{"type":"string","title":"The name of the poll"},"description":{"type":"string","title":"Description of the poll"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the poll"},"stop_function_name":{"type":"string","title":"Required stop function name"},"output_concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books":{"get":{"summary":"View Workspace Books","description":"This endpoint returns metadata for all books that are currently available\nin the runtime for the specified workspace, including their names, versions,\ndescriptions, authentication requirements, and capabilities.","operationId":"ListWorkspaceBooks","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBooksResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of books to return.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The token to use to retrieve the next page of books.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Workspace Book Procedures > This endpoint returns a list of all procedures (functions/operations) that\ > can be invoked on the specified book in the workspace, along with their signatures,\ > input/output parameters, and metadata such as descriptions and examples. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookProceduresResponse":{"type":"object","properties":{"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Available procedures"}},"title":"Retrieve all the available signatures for a book"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{name}/{version}/procedures":{"get":{"summary":"View Workspace Book Procedures","description":"This endpoint returns a list of all procedures (functions/operations) that\ncan be invoked on the specified book in the workspace, along with their signatures,\ninput/output parameters, and metadata such as descriptions and examples.","operationId":"ListWorkspaceBookProcedures","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Workspace Book Concepts > This endpoint returns a list of concept descriptors defined by the\ > specified book in the workspace, which can be referenced by procedures as inputs or outputs. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookConceptsResponse":{"type":"object","properties":{"concepts":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Available concepts"}},"title":"Retrieve all the available concept descriptors for a book"},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{name}/{version}/concepts":{"get":{"summary":"View Workspace Book Concepts","description":"This endpoint returns a list of concept descriptors defined by the\nspecified book in the workspace, which can be referenced by procedures as inputs or outputs.","operationId":"ListWorkspaceBookConcepts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookConceptsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Connection Discoverables > This endpoint returns a list of entities (like database tables, API endpoints,\ > file systems, etc.) that can be discovered from a specific book connection\ > and potentially converted into executable procedures. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveDiscoverablesResponse":{"type":"object","properties":{"discoverables":{"type":"array","items":{"$ref":"#/components/schemas/v2Discoverable"},"title":"The retrieved Discoverables"}},"title":"The response to a get discoverables request"},"v2Discoverable":{"type":"object","properties":{"name":{"type":"string","title":"The name of the discoverable"},"description":{"type":"string","title":"The description of the discoverable"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/discoverables":{"get":{"summary":"View Connection Discoverables","description":"This endpoint returns a list of entities (like database tables, API endpoints,\nfile systems, etc.) that can be discovered from a specific book connection\nand potentially converted into executable procedures.","operationId":"ListWorkspaceBookConnectionDiscoverables","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveDiscoverablesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"search","description":"A search term to filter the discoverables","in":"query","required":false,"schema":{"type":"string"}},{"name":"offset","description":"The starting point within the data set from which records will be returned.\nUsed for pagination.","in":"query","required":false,"schema":{"type":"string","format":"uint64"}},{"name":"limit","description":"The maximum number of records to return from the data set.\nUsed for pagination.","in":"query","required":false,"schema":{"type":"string","format":"uint64"}}],"tags":["Books"]}}}} ``` ## Search Book Procedures > This endpoint returns ranked procedures that best match the provided query.\ > Each result includes the owning book name and version, a full procedure descriptor,\ > and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchBookProceduresResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchBookProcedureMatch"},"title":"Ranked list of matches for the given query"}},"title":"Search results for book procedures"},"v2SearchBookProcedureMatch":{"type":"object","properties":{"book_name":{"type":"string","title":"Book name owning the procedure"},"book_version":{"type":"string","title":"Book version owning the procedure"},"procedure":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"}},"title":"A match result for a searched procedure"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"v2SearchBookProceduresRequest":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against procedure metadata and signatures"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for procedures across all available books"}}},"paths":{"/api/v1/procedures:search":{"post":{"summary":"Search Book Procedures","description":"This endpoint returns ranked procedures that best match the provided query.\nEach result includes the owning book name and version, a full procedure descriptor,\nand a relevance score.","operationId":"SearchBookProcedures","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBookProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBookProceduresRequest"}}},"required":true},"tags":["Books"]}}}} ``` ## Search Books > This endpoint returns ranked books that best match the provided query.\ > Each result includes a full book descriptor and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchBooksResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchBookMatch"},"title":"Ranked list of book matches for the given query"}},"title":"Search results for books"},"v2SearchBookMatch":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/v2BookDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"}},"title":"A match result for a searched book"},"v2BookDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"@deprecated, use name and version to uniquely identify a book","title":"The identifier of the book (a.k.a integration_id)"},"name":{"type":"string","title":"The name of the book"},"short_description":{"type":"string","title":"Short description of the book"},"long_description":{"type":"string","title":"Short description of the book"},"author":{"type":"string","title":"Author of the book"},"icon":{"type":"string","format":"byte","title":"Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP)"},"version":{"type":"string","title":"Version of the book"},"authentications":{"type":"array","items":{"$ref":"#/components/schemas/v2BookAuthenticationDescriptor"},"title":"Authentication mechanism for a book version"},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book. Note: replaced by config_map"},"display_name":{"type":"string","title":"Display name of the book"},"endpoint":{"type":"string","title":"URI location of the book, such as lambda://microsoft/1.0.4"},"connection_required":{"type":"boolean","description":"Connection Required. True if all procedures always require a connection."},"discover_capable":{"type":"boolean","title":"True if the book is capable of discovering book procedures"},"tags":{"type":"array","items":{"type":"string"},"title":"Tags associated with the book"},"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Book procedures"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"userinfo_capable":{"type":"boolean","title":"True if the book is capable of returning oauth user's info"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/v2BookTriggerDescriptor"},"title":"Book triggers"},"bdk_runtime_version":{"type":"string","title":"BDK Runtime version"},"environment_information":{"$ref":"#/components/schemas/bdkV2EnvironmentInformation"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book"},"hidden":{"type":"boolean","title":"True if the book is hidden"},"polls":{"type":"array","items":{"$ref":"#/components/schemas/v2BookPollDescriptor"},"title":"Book polls"}}},"v2BookAuthenticationDescriptor":{"type":"object","properties":{"custom":{"$ref":"#/components/schemas/v2BookCustomAuthenticationDescriptor"},"oauth":{"$ref":"#/components/schemas/v2BookOAuthAuthenticationDescriptor"}}},"v2BookCustomAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credentials required to perform authentication"},"description":{"type":"string","title":"A description of the authentication"},"name":{"type":"string","title":"A name for the authentication"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2CredentialDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"type":{"$ref":"#/components/schemas/v2CredentialType"},"label":{"type":"string","title":"Label that will be displayed to the user during configuration of the book"},"visible":{"type":"boolean","description":"True if the value is visible to the book, false otherwise."},"description":{"type":"string","title":"Description"}}},"v2CredentialType":{"type":"string","enum":["CredentialTypeText","CredentialTypeSensitiveText"],"default":"CredentialTypeText","title":"Supported configuration types"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2BookOAuthAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"provider":{"$ref":"#/components/schemas/v2OAuthProvider"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthFlow"},"title":"Supported OAuth flows"},"authorize_endpoint":{"type":"string","title":"Authorize endpoint"},"token_endpoint":{"type":"string","title":"Token endpoint"},"scope":{"type":"array","items":{"type":"string"},"title":"Scopes"},"name":{"type":"string","title":"A name for the authentication"},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthArgumentDescriptor"},"title":"Additional arguments which are not part of the OAuth specification\nbut are required for the authentication to work (such as tenant_id)"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credential descriptors"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2OAuthProvider":{"type":"string","enum":["OAuthProviderMicrosoft","OAuthProviderGoogle","OAuthProviderGeneric"],"default":"OAuthProviderMicrosoft","title":"Supported OAuth providers"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"},"v2OAuthArgumentDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the parameter"},"name":{"type":"string","title":"Name of the parameter"},"description":{"type":"string","title":"Description of the parameter"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2BookTriggerDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger"},"name":{"type":"string","title":"The name of the trigger"},"description":{"type":"string","title":"Description of the trigger"},"setup_description":{"type":"string","title":"Setup description for the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the trigger"},"filter_capable":{"type":"boolean","title":"True if the trigger is capable of filtering events"},"is_manual":{"type":"boolean","title":"True if the trigger is manually invoked"},"event_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Event type schema for the trigger"},"is_shared_endpoint":{"type":"boolean","description":"True if every trigger instance of this trigger shares the same endpoint when configured."}}},"bdkV2EnvironmentInformation":{"type":"object","properties":{"version":{"type":"string"},"runtime_name":{"type":"string","title":"Runtime name"},"runtime_version":{"type":"string","title":"Runtime version"},"bci_protocol_version":{"type":"string","title":"BCI Protocol version"},"api_version":{"type":"string","title":"BDK API Version"},"path":{"type":"array","items":{"type":"string"},"title":"Book path under which books will be discovered"}},"title":"Information about the environment"},"v2BookPollDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the poll"},"name":{"type":"string","title":"The name of the poll"},"description":{"type":"string","title":"Description of the poll"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the poll"},"stop_function_name":{"type":"string","title":"Required stop function name"},"output_concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"v2SearchBooksRequest":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against book name, version, tags, or descriptions"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for books across the library"}}},"paths":{"/api/v1/books:search":{"post":{"summary":"Search Books","description":"This endpoint returns ranked books that best match the provided query.\nEach result includes a full book descriptor and a relevance score.","operationId":"SearchBooks","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBooksResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBooksRequest"}}},"required":true},"tags":["Books"]}}}} ``` ## Search Book Concepts > This endpoint returns ranked concepts that best match the provided query.\ > Each result includes the owning book name, version, a full concept descriptor, and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchBookConceptsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchBookConceptMatch"},"title":"Ranked list of concept matches for the given query"}},"title":"Search results for book concepts"},"v2SearchBookConceptMatch":{"type":"object","properties":{"book_name":{"type":"string","title":"Book name containing the concept"},"book_version":{"type":"string","title":"Book version containing the concept"},"concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"}},"title":"A match result for a searched concept"},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"v2SearchBookConceptsRequest":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against concept names and descriptions"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for concepts across all available books"}}},"paths":{"/api/v1/concepts:search":{"post":{"summary":"Search Book Concepts","description":"This endpoint returns ranked concepts that best match the provided query.\nEach result includes the owning book name, version, a full concept descriptor, and a relevance score.","operationId":"SearchBookConcepts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBookConceptsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBookConceptsRequest"}}},"required":true},"tags":["Books"]}}}} ``` ## Search Workspace Book Procedures > This endpoint returns ranked procedures that best match the provided query.\ > Each result includes the owning book name and version, a full procedure descriptor,\ > and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchWorkspaceBookProceduresResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchWorkspaceBookProcedureMatch"},"title":"Ranked list of matches for the given query"}},"title":"Search results for workspace book procedures (static and discovered)"},"v2SearchWorkspaceBookProcedureMatch":{"type":"object","properties":{"book_name":{"type":"string","title":"Book name owning the procedure"},"book_version":{"type":"string","title":"Book version owning the procedure"},"procedure":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"},"organization_id":{"type":"string","title":"Organization ID"},"workspace_id":{"type":"string","title":"Workspace ID"},"connection_id":{"type":"string","title":"Connection ID"}},"title":"A match result for a searched procedure (static or discovered)"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SearchWorkspaceBookProceduresBody":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against procedure metadata and signatures"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for procedures across all available books in a workspace"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/procedures:search":{"post":{"summary":"Search Workspace Book Procedures","description":"This endpoint returns ranked procedures that best match the provided query.\nEach result includes the owning book name and version, a full procedure descriptor,\nand a relevance score.","operationId":"SearchWorkspaceBookProcedures","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchWorkspaceBookProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchWorkspaceBookProceduresBody"}}},"required":true},"tags":["Books"]}}}} ``` ## Search Connection Procedures > This endpoint returns ranked procedures that best match the provided query.\ > Each result includes the owning book name and version, a full procedure descriptor,\ > and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchWorkspaceBookProceduresResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchWorkspaceBookProcedureMatch"},"title":"Ranked list of matches for the given query"}},"title":"Search results for workspace book procedures (static and discovered)"},"v2SearchWorkspaceBookProcedureMatch":{"type":"object","properties":{"book_name":{"type":"string","title":"Book name owning the procedure"},"book_version":{"type":"string","title":"Book version owning the procedure"},"procedure":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"},"organization_id":{"type":"string","title":"Organization ID"},"workspace_id":{"type":"string","title":"Workspace ID"},"connection_id":{"type":"string","title":"Connection ID"}},"title":"A match result for a searched procedure (static or discovered)"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SearchWorkspaceBookConnectionProceduresBody":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against procedure metadata and signatures"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for procedures across all available books in a connection"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/procedures:search":{"post":{"summary":"Search Connection Procedures","description":"This endpoint returns ranked procedures that best match the provided query.\nEach result includes the owning book name and version, a full procedure descriptor,\nand a relevance score.","operationId":"SearchWorkspaceBookConnectionProcedures","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchWorkspaceBookProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchWorkspaceBookConnectionProceduresBody"}}},"required":true},"tags":["Books"]}}}} ``` ## Search Workspace Books > This endpoint returns ranked books that best match the provided query.\ > Each result includes a full book descriptor and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchBooksResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchBookMatch"},"title":"Ranked list of book matches for the given query"}},"title":"Search results for books"},"v2SearchBookMatch":{"type":"object","properties":{"book":{"$ref":"#/components/schemas/v2BookDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"}},"title":"A match result for a searched book"},"v2BookDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"@deprecated, use name and version to uniquely identify a book","title":"The identifier of the book (a.k.a integration_id)"},"name":{"type":"string","title":"The name of the book"},"short_description":{"type":"string","title":"Short description of the book"},"long_description":{"type":"string","title":"Short description of the book"},"author":{"type":"string","title":"Author of the book"},"icon":{"type":"string","format":"byte","title":"Icon of the book in an image format that is web-compatible (i.e. JPG, PNG, SVG, WebP)"},"version":{"type":"string","title":"Version of the book"},"authentications":{"type":"array","items":{"$ref":"#/components/schemas/v2BookAuthenticationDescriptor"},"title":"Authentication mechanism for a book version"},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book. Note: replaced by config_map"},"display_name":{"type":"string","title":"Display name of the book"},"endpoint":{"type":"string","title":"URI location of the book, such as lambda://microsoft/1.0.4"},"connection_required":{"type":"boolean","description":"Connection Required. True if all procedures always require a connection."},"discover_capable":{"type":"boolean","title":"True if the book is capable of discovering book procedures"},"tags":{"type":"array","items":{"type":"string"},"title":"Tags associated with the book"},"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Book procedures"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"userinfo_capable":{"type":"boolean","title":"True if the book is capable of returning oauth user's info"},"triggers":{"type":"array","items":{"$ref":"#/components/schemas/v2BookTriggerDescriptor"},"title":"Book triggers"},"bdk_runtime_version":{"type":"string","title":"BDK Runtime version"},"environment_information":{"$ref":"#/components/schemas/bdkV2EnvironmentInformation"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the parameters available for configuring the behaviour of this book"},"hidden":{"type":"boolean","title":"True if the book is hidden"},"polls":{"type":"array","items":{"$ref":"#/components/schemas/v2BookPollDescriptor"},"title":"Book polls"}}},"v2BookAuthenticationDescriptor":{"type":"object","properties":{"custom":{"$ref":"#/components/schemas/v2BookCustomAuthenticationDescriptor"},"oauth":{"$ref":"#/components/schemas/v2BookOAuthAuthenticationDescriptor"}}},"v2BookCustomAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credentials required to perform authentication"},"description":{"type":"string","title":"A description of the authentication"},"name":{"type":"string","title":"A name for the authentication"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2CredentialDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"type":{"$ref":"#/components/schemas/v2CredentialType"},"label":{"type":"string","title":"Label that will be displayed to the user during configuration of the book"},"visible":{"type":"boolean","description":"True if the value is visible to the book, false otherwise."},"description":{"type":"string","title":"Description"}}},"v2CredentialType":{"type":"string","enum":["CredentialTypeText","CredentialTypeSensitiveText"],"default":"CredentialTypeText","title":"Supported configuration types"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2BookOAuthAuthenticationDescriptor":{"type":"object","properties":{"id":{"type":"string","description":"Since books can have multiple authentication mechanisms there is\nand ID to differentiate each mechanism."},"provider":{"$ref":"#/components/schemas/v2OAuthProvider"},"flows":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthFlow"},"title":"Supported OAuth flows"},"authorize_endpoint":{"type":"string","title":"Authorize endpoint"},"token_endpoint":{"type":"string","title":"Token endpoint"},"scope":{"type":"array","items":{"type":"string"},"title":"Scopes"},"name":{"type":"string","title":"A name for the authentication"},"arguments":{"type":"array","items":{"$ref":"#/components/schemas/v2OAuthArgumentDescriptor"},"title":"Additional arguments which are not part of the OAuth specification\nbut are required for the authentication to work (such as tenant_id)"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialDescriptor"},"title":"Credential descriptors"},"preferred":{"type":"boolean","title":"If this is a preferred authentication method"}}},"v2OAuthProvider":{"type":"string","enum":["OAuthProviderMicrosoft","OAuthProviderGoogle","OAuthProviderGeneric"],"default":"OAuthProviderMicrosoft","title":"Supported OAuth providers"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"},"v2OAuthArgumentDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the parameter"},"name":{"type":"string","title":"Name of the parameter"},"description":{"type":"string","title":"Description of the parameter"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2BookTriggerDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger"},"name":{"type":"string","title":"The name of the trigger"},"description":{"type":"string","title":"Description of the trigger"},"setup_description":{"type":"string","title":"Setup description for the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the trigger"},"filter_capable":{"type":"boolean","title":"True if the trigger is capable of filtering events"},"is_manual":{"type":"boolean","title":"True if the trigger is manually invoked"},"event_type":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Event type schema for the trigger"},"is_shared_endpoint":{"type":"boolean","description":"True if every trigger instance of this trigger shares the same endpoint when configured."}}},"bdkV2EnvironmentInformation":{"type":"object","properties":{"version":{"type":"string"},"runtime_name":{"type":"string","title":"Runtime name"},"runtime_version":{"type":"string","title":"Runtime version"},"bci_protocol_version":{"type":"string","title":"BCI Protocol version"},"api_version":{"type":"string","title":"BDK API Version"},"path":{"type":"array","items":{"type":"string"},"title":"Book path under which books will be discovered"}},"title":"Information about the environment"},"v2BookPollDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the poll"},"name":{"type":"string","title":"The name of the poll"},"description":{"type":"string","title":"Description of the poll"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"Configuration parameters for the poll"},"stop_function_name":{"type":"string","title":"Required stop function name"},"output_concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SearchWorkspaceBooksBody":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against book name, version, tags, or descriptions"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for books across the library in a workspace"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books:search":{"post":{"summary":"Search Workspace Books","description":"This endpoint returns ranked books that best match the provided query.\nEach result includes a full book descriptor and a relevance score.","operationId":"SearchWorkspaceBooks","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBooksResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchWorkspaceBooksBody"}}},"required":true},"tags":["Books"]}}}} ``` ## Search Workspace Book Concepts > This endpoint returns ranked concepts that best match the provided query.\ > Each result includes the owning book name, version, a full concept descriptor, and a relevance score. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SearchBookConceptsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v2SearchBookConceptMatch"},"title":"Ranked list of concept matches for the given query"}},"title":"Search results for book concepts"},"v2SearchBookConceptMatch":{"type":"object","properties":{"book_name":{"type":"string","title":"Book name containing the concept"},"book_version":{"type":"string","title":"Book version containing the concept"},"concept":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"score":{"type":"number","format":"double","title":"Relevance score (higher is better)"}},"title":"A match result for a searched concept"},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SearchWorkspaceBookConceptsBody":{"type":"object","properties":{"query":{"type":"string","title":"Free-text search query to match against concept names and descriptions"},"top_k":{"type":"integer","format":"int64","title":"Maximum number of results to return"},"max_distance":{"type":"number","format":"float","title":"Maximum distance threshold for similarity matching"}},"title":"Search for concepts across all available books in a workspace"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/concepts:search":{"post":{"summary":"Search Workspace Book Concepts","description":"This endpoint returns ranked concepts that best match the provided query.\nEach result includes the owning book name, version, a full concept descriptor, and a relevance score.","operationId":"SearchWorkspaceBookConcepts","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SearchBookConceptsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchWorkspaceBookConceptsBody"}}},"required":true},"tags":["Books"]}}}} ``` ## View Book Connections > This endpoint returns a list of all connections of a book version. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookConnectionsResponse":{"type":"object","properties":{"book_connections":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"},"title":"The list of book connections"},"next_page_token":{"type":"string","description":"The token to use to retrieve the next page of connections."}}},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections":{"get":{"summary":"View Book Connections","description":"This endpoint returns a list of all connections of a book version.","operationId":"ListWorkspaceBookConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of connections to return.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The token to use to retrieve the next page of connections.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## Create Book Connection > This endpoint adds a new book connection, which can be used to invoke\ > procedures on the book. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2BookConnectionResponse":{"type":"object","properties":{"book_connection_descriptor":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"},"authorize_url":{"$ref":"#/components/schemas/v2BookConnectionOAuthURLResponse"}},"title":"The response to an add/update book connection request"},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"v2BookConnectionOAuthURLResponse":{"type":"object","properties":{"url":{"type":"string","title":"The URL to kick off the OAuth flow. It contains:\n- The authorize endpoint\n- The state\n- The scope\n- The redirect uri"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AddWorkspaceBookConnectionBody":{"type":"object","properties":{"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configuration for the connection"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"oauth_flow":{"$ref":"#/components/schemas/v2OAuthFlow"}},"title":"The book connection to add"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections":{"post":{"summary":"Create Book Connection","description":"This endpoint adds a new book connection, which can be used to invoke\nprocedures on the book.","operationId":"AddWorkspaceBookConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2BookConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddWorkspaceBookConnectionBody"}}},"required":true},"tags":["Books"]}}}} ``` ## Update Book Connection > This endpoint updates a book connection in the library. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2BookConnectionResponse":{"type":"object","properties":{"book_connection_descriptor":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"},"authorize_url":{"$ref":"#/components/schemas/v2BookConnectionOAuthURLResponse"}},"title":"The response to an add/update book connection request"},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"v2BookConnectionOAuthURLResponse":{"type":"object","properties":{"url":{"type":"string","title":"The URL to kick off the OAuth flow. It contains:\n- The authorize endpoint\n- The state\n- The scope\n- The redirect uri"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"UpdateWorkspaceBookConnectionBody":{"type":"object","properties":{"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Input config"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"oauth_flow":{"$ref":"#/components/schemas/v2OAuthFlow"}},"title":"The book connection to update"},"v2OAuthFlow":{"type":"string","enum":["OAuthFlowAuthorizationCode","OAuthFlowClientCredentials"],"default":"OAuthFlowAuthorizationCode","title":"Supported OAuth flows"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}":{"put":{"summary":"Update Book Connection","description":"This endpoint updates a book connection in the library.","operationId":"UpdateWorkspaceBookConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2BookConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceBookConnectionBody"}}},"required":true},"tags":["Books"]}}}} ``` ## View Connection > This endpoint returns a specific book connection. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookConnectionResponse":{"type":"object","properties":{"book_connection":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"}}},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}":{"get":{"summary":"View Connection","description":"This endpoint returns a specific book connection.","operationId":"GetWorkspaceBookConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/connections > View All Connections ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBooksConnectionsResponse":{"type":"object","properties":{"book_connections":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"},"title":"The list of book connections"},"next_page_token":{"type":"string","description":"The token to use to retrieve the next page of connections."}}},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections":{"get":{"summary":"View All Connections","operationId":"ListAllWorkspaceBookConnections","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBooksConnectionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of connections to return.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The token to use to retrieve the next page of connections.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"AIP-160 Filtering\nhttps://google.aip.dev/160","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## Upgrade Book Connection > This endpoint upgrades a book connection to a new version. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2BookConnectionResponse":{"type":"object","properties":{"book_connection_descriptor":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"},"authorize_url":{"$ref":"#/components/schemas/v2BookConnectionOAuthURLResponse"}},"title":"The response to an add/update book connection request"},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"v2BookConnectionOAuthURLResponse":{"type":"object","properties":{"url":{"type":"string","title":"The URL to kick off the OAuth flow. It contains:\n- The authorize endpoint\n- The state\n- The scope\n- The redirect uri"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"UpgradeWorkspaceBookConnectionBody":{"type":"object","properties":{"new_book_version":{"type":"string","title":"The new version to upgrade book to"}}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/upgrade":{"put":{"summary":"Upgrade Book Connection","description":"This endpoint upgrades a book connection to a new version.","operationId":"UpgradeWorkspaceBookConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2BookConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeWorkspaceBookConnectionBody"}}},"required":true},"tags":["Books"]}}}} ``` ## Authorize Connection > This endpoint generates a new authrization url for an existing book connection. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2BookConnectionResponse":{"type":"object","properties":{"book_connection_descriptor":{"$ref":"#/components/schemas/v2BookConnectionDescriptor"},"authorize_url":{"$ref":"#/components/schemas/v2BookConnectionOAuthURLResponse"}},"title":"The response to an add/update book connection request"},"v2BookConnectionDescriptor":{"type":"object","properties":{"book_name":{"type":"string","title":"The name of the book"},"book_version":{"type":"string","title":"The version of the book"},"connection_id":{"type":"string","title":"The connection id of the book"},"connection_name":{"type":"string","title":"The connection name"},"authentication":{"$ref":"#/components/schemas/v2Authentication"},"config":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptValue"},"title":"Input config concepts. Note: replaced by config_map"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Label"},"title":"Labels associated with the connection"},"status":{"$ref":"#/components/schemas/v2BookConnectionStatus"},"endpoint":{"type":"string","title":"The endpoint of the connection"},"discovered":{"type":"array","items":{"type":"string"},"title":"The list of things that have been discovered"},"config_map":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configured values"}}},"v2Authentication":{"type":"object","properties":{"authentication_id":{"type":"string","title":"Identifier of the authentication method to be used for testing the connection"},"authentication_credentials":{"type":"array","items":{"$ref":"#/components/schemas/v2CredentialValue"},"title":"Credentials"}}},"v2CredentialValue":{"type":"object","properties":{"id":{"type":"string","title":"Id of the credential"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConceptValue":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"bdkV2Label":{"type":"object","properties":{"key":{"type":"string","title":"The key of the key-value pair"},"value":{"type":"string","title":"The value of the key-value pair"}}},"v2BookConnectionStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2BookConnectionState"},"state_category":{"$ref":"#/components/schemas/v2BookConnectionStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/v2BookConnectionCondition"},"title":"List of conditions that apply to the BookConnection"}},"title":"Status information for a BookConnection"},"v2BookConnectionState":{"type":"string","enum":["BOOK_CONNECTION_STATE_PENDING","BOOK_CONNECTION_STATE_READY","BOOK_CONNECTION_STATE_FAILED","BOOK_CONNECTION_STATE_CONDITIONS_NOT_MET","BOOK_CONNECTION_STATE_UNKNOWN"],"default":"BOOK_CONNECTION_STATE_PENDING","title":"Possible phases for a BookConnection (Pending, ConditionsNotMet, Ready, Failed, Unknown)"},"v2BookConnectionStateCategory":{"type":"string","enum":["BOOK_CONNECTION_STATE_CATEGORY_WARNING","BOOK_CONNECTION_STATE_CATEGORY_READY","BOOK_CONNECTION_STATE_CATEGORY_FAILED"],"default":"BOOK_CONNECTION_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"v2BookConnectionCondition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/v2BookConnectionConditionType"},"status":{"$ref":"#/components/schemas/v2BookConnectionConditionStatus"},"last_transition_time":{"type":"string","title":"RFC 3339 timestamp of when this condition was last updated"},"reason":{"type":"string","title":"Brief reason explaining the condition"},"reason_code":{"$ref":"#/components/schemas/v2BookConnectionConditionReasonCode"}},"title":"Condition information for BookConnection"},"v2BookConnectionConditionType":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","BOOK_CONNECTION_CONDITION_TYPE_AUTHENTICATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_CONFIGURATION_VALID","BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY","BOOK_CONNECTION_CONDITION_TYPE_CREDENTIALS_VALID","BOOK_CONNECTION_CONDITION_TYPE_DISCOVER_READY","BOOK_CONNECTION_CONDITION_TYPE_TRIGGER_INSTANCES_READY","BOOK_CONNECTION_CONDITION_TYPE_COMPATIBLE_RUNTIME_VERSION"],"default":"BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID","description":"Represents the various condition types that can be associated with a BookConnection.\n\nConditions are categorized into two groups:\n\n1. [Static Conditions] These conditions are determined solely by the BookConnection's data structure\n and configuration, and they can be validated without external dependencies or runtime state:\n - BOOK_VALID\n - AUTHENTICATION_VALID\n - CONFIGURATION_VALID\n\n2. [Dynamic Conditions] These conditions depend on external factors and runtime state that can change\n independently of the BookConnection spec. They require active monitoring and periodic re-evaluation:\n - DEPLOYMENT_READY\n - CREDENTIALS_VALID\n - DISCOVER_READY\n - TRIGGER_INSTANCES_READY\n - COMPATIBLE_RUNTIME_VERSION\n\n - BOOK_CONNECTION_CONDITION_TYPE_BOOK_VALID: Static\n - BOOK_CONNECTION_CONDITION_TYPE_DEPLOYMENT_READY: Dynamic"},"v2BookConnectionConditionStatus":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_STATUS_TRUE","BOOK_CONNECTION_CONDITION_STATUS_FALSE","BOOK_CONNECTION_CONDITION_STATUS_UNKNOWN","BOOK_CONNECTION_CONDITION_STATUS_PENDING"],"default":"BOOK_CONNECTION_CONDITION_STATUS_TRUE","description":"Possible Values:\n - True: All good\n - False: An error occurred\n - Unknown: Condition not applicable/relevant\n - Pending: Underlying process (upon which the condition depends) still ongoing","title":"Status values for conditions"},"v2BookConnectionConditionReasonCode":{"type":"string","enum":["BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_MISSING_IMAGE","BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_RUNTIME_VERSION_OUTDATED","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_MISSING_CREDENTIAL","BOOK_CONNECTION_CONDITION_REASON_CODE_WRONG_CREDENTIAL_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_NOT_FOUND","BOOK_CONNECTION_CONDITION_REASON_CODE_SECRET_MISSING_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_REQUIRED_MISSING","BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_TEST_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_TOKEN_REFRESH_FAILED","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY","BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_WRONG_TYPE","BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO","BOOK_CONNECTION_CONDITION_REASON_CODE_NEW_DEPLOYMENT_ROLLED_OUT","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS","BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_FAILED"],"default":"BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED","description":"- BOOK_CONNECTION_CONDITION_REASON_CODE_BOOK_LOOKUP_FAILED: Book related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_AUTHENTICATION_ID_NOT_FOUND: Authentication related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_CONFIGURATION_UNKNOWN_KEY: Configuration related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_REPLICA_COUNT_IS_ZERO: Connection related\n - BOOK_CONNECTION_CONDITION_REASON_CODE_DISCOVER_IN_PROGRESS: Discover related","title":"Machine-readable reason codes for condition transitions"},"v2BookConnectionOAuthURLResponse":{"type":"object","properties":{"url":{"type":"string","title":"The URL to kick off the OAuth flow. It contains:\n- The authorize endpoint\n- The state\n- The scope\n- The redirect uri"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/authorize":{"put":{"summary":"Authorize Connection","description":"This endpoint generates a new authrization url for an existing book connection.","operationId":"AuthorizeWorkspaceBookConnection","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2BookConnectionResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## Discover Connection Procedures > This endpoint allows books to discover and register new procedures\ > at runtime by connecting to external APIs, databases, or services.\ > The discovered procedures become available for invocation.\ > \ > Supports:\ > \- Specification of what entities to discover\ > \- Dynamic procedure registration\ > \ > Note: This will override any existing discoverables, and sending an empty list will remove all discoverables. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2DiscoverWorkspaceBookConnectionProceduresResponse":{"type":"object","title":"A response that is sent to reply to a library discovery request"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SetDiscoveredBody":{"type":"object","properties":{"what":{"type":"array","items":{"type":"string"},"title":"What should be discovered"}}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/discover":{"post":{"summary":"Discover Connection Procedures","description":"This endpoint allows books to discover and register new procedures\nat runtime by connecting to external APIs, databases, or services.\nThe discovered procedures become available for invocation.\n\nSupports:\n- Specification of what entities to discover\n- Dynamic procedure registration\n\nNote: This will override any existing discoverables, and sending an empty list will remove all discoverables.","operationId":"SetDiscovered","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2DiscoverWorkspaceBookConnectionProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDiscoveredBody"}}},"required":true},"tags":["Books"]}}}} ``` ## View Connection Procedures > This endpoint returns a list of all procedures (functions/operations) that\ > can be invoked on the specified book connection in the workspace, along with their signatures,\ > input/output parameters, and metadata such as descriptions and examples. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveBookProceduresResponse":{"type":"object","properties":{"procedures":{"type":"array","items":{"$ref":"#/components/schemas/v2BookProcedureDescriptor"},"title":"Available procedures"}},"title":"Retrieve all the available signatures for a book"},"v2BookProcedureDescriptor":{"type":"object","properties":{"id":{"type":"string","title":"Id of the procedure to use in subsequent calls"},"signature":{"$ref":"#/components/schemas/v2BookProcedureSignature"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the inputs for the procedure (required and non required)"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDescriptor"},"title":"All the outputs for the procedure"},"short_description":{"type":"string","title":"Short description"},"long_description":{"type":"string","title":"Longer description"},"filter_capable":{"type":"boolean","title":"Can this procedure filter its response?"},"page_capable":{"type":"boolean","title":"Can this procedure page its response?"},"connection_required":{"$ref":"#/components/schemas/v2ConnectionRequired"},"is_discovered":{"type":"boolean","title":"True if the procedure was discovered"},"questions":{"type":"array","items":{"$ref":"#/components/schemas/v2QuestionDescriptor"},"title":"Questions the procedure may ask"},"is_async":{"type":"boolean","title":"Does the procedure return a promise?"},"is_mutation":{"type":"boolean","title":"True if the procedures performs a mutating action"},"search_hints":{"type":"array","items":{"type":"string"},"title":"Search hints used for procedure resolution"}}},"v2BookProcedureSignature":{"type":"object","properties":{"english":{"type":"string"},"verbs":{"type":"array","items":{"type":"string"},"title":"Verb of the signature"},"object":{"$ref":"#/components/schemas/v2NounPhrases"},"preposition":{"type":"string","title":"Preposition"},"target":{"$ref":"#/components/schemas/v2NounPhrases"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrases"},"title":"Outputs"},"proper_nouns":{"type":"array","items":{"type":"string"},"title":"All the proper nouns that appear on this signature"}}},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2ConceptDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string","title":"Description"},"default_value":{"$ref":"#/components/schemas/bdkV2Value"}}},"v2ConceptType":{"type":"object","properties":{"scalar_type":{"$ref":"#/components/schemas/v2ConceptScalarType"},"optional_type":{"$ref":"#/components/schemas/v2ConceptOptionalType"},"list_type":{"$ref":"#/components/schemas/v2ConceptListType"},"dictionary_type":{"$ref":"#/components/schemas/v2ConceptDictionaryType"},"table_type":{"$ref":"#/components/schemas/v2ConceptTableType"},"opaque_type":{"$ref":"#/components/schemas/v2ConceptOpaqueType"},"any_type":{"$ref":"#/components/schemas/v2ConceptAnyType"},"union_type":{"$ref":"#/components/schemas/v2ConceptUnionType"},"self_type":{"$ref":"#/components/schemas/v2ConceptSelfType"},"sensitive_type":{"$ref":"#/components/schemas/v2ConceptSensitiveType"},"enum_type":{"$ref":"#/components/schemas/v2ConceptEnumType"}}},"v2ConceptScalarType":{"type":"string","enum":["ConceptScalarTypeConceptual","ConceptScalarTypeText","ConceptScalarTypeNumber","ConceptScalarTypeBoolean","ConceptScalarTypeDatetime","ConceptScalarTypeDate","ConceptScalarTypeTime","ConceptScalarTypeFile","ConceptScalarTypeUUID"],"default":"ConceptScalarTypeConceptual","title":"Supported concept types"},"v2ConceptOptionalType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptListType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptDictionaryType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptDictionaryTypeField"}},"description":{"type":"string"}}},"v2ConceptDictionaryTypeField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptTableType":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptTableTypeColumn"}},"description":{"type":"string"}}},"v2ConceptTableTypeColumn":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/v2ConceptType"},"description":{"type":"string"}}},"v2ConceptOpaqueType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"description":{"type":"string"}}},"v2ConceptAnyType":{"type":"object"},"v2ConceptUnionType":{"type":"object","properties":{"inners":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptType"}}}},"v2ConceptSelfType":{"type":"object"},"v2ConceptSensitiveType":{"type":"object","properties":{"inner":{"$ref":"#/components/schemas/v2ConceptType"}}},"v2ConceptEnumType":{"type":"object","properties":{"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/v2ConceptEnumTypeMember"}},"description":{"type":"string"}}},"v2ConceptEnumTypeMember":{"type":"object","properties":{"name":{"type":"string"},"noun_phrase":{"$ref":"#/components/schemas/v2NounPhrase"},"description":{"type":"string"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2ConnectionRequired":{"type":"string","enum":["Optional","Always","Never"],"default":"Optional","title":"Connection required"},"v2QuestionDescriptor":{"type":"object","properties":{"noun_phrases":{"$ref":"#/components/schemas/v2NounPhrases"},"type":{"$ref":"#/components/schemas/v2ConceptType"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/procedures":{"get":{"summary":"View Connection Procedures","description":"This endpoint returns a list of all procedures (functions/operations) that\ncan be invoked on the specified book connection in the workspace, along with their signatures,\ninput/output parameters, and metadata such as descriptions and examples.","operationId":"ListWorkspaceBookConnectionProcedures","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveBookProceduresResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/books/{book\_name}/{book\_version}/connections/{connection\_id}/triggers > Create Trigger Instance ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2AddWorkspaceBookConnectionTriggerInstanceResponse":{"type":"object","properties":{"trigger_instance":{"$ref":"#/components/schemas/v2TriggerInstance"}}},"v2TriggerInstance":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger instance"},"name":{"type":"string","title":"The name of the trigger instance"},"reference":{"type":"string","title":"The reference of the trigger instance"},"book_name":{"type":"string","title":"The name of the book"},"connection_id":{"type":"string","title":"The identifier of the book connection"},"trigger_id":{"type":"string","title":"The name of the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configuration parameters for the trigger"},"endpoint":{"type":"string","title":"The endpoint of the trigger instance"},"automation_ids":{"type":"array","items":{"type":"string"},"title":"Automation IDs"},"workspace_id":{"type":"string","title":"Workspace ID"},"organization_id":{"type":"string","title":"Organization ID"},"filter_expression":{"$ref":"#/components/schemas/v2Expression"},"status":{"$ref":"#/components/schemas/v2TriggerInstanceStatus"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2Expression":{"type":"object","properties":{"binary_expression":{"$ref":"#/components/schemas/v2BinaryExpression"},"unary_expression":{"$ref":"#/components/schemas/v2UnaryExpression"},"value_expression":{"$ref":"#/components/schemas/bdkV2Value"},"noun_phrases_expression":{"$ref":"#/components/schemas/v2NounPhrases"}}},"v2BinaryExpression":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/v2BinaryOperator"},"left":{"$ref":"#/components/schemas/v2Expression"},"right":{"$ref":"#/components/schemas/v2Expression"}}},"v2BinaryOperator":{"type":"string","enum":["BinaryOperatorAnd","BinaryOperatorOr","BinaryOperatorEquals","BinaryOperatorNotEquals","BinaryOperatorIn","BinaryOperatorHas","BinaryOperatorLessThan","BinaryOperatorGreaterThan","BinaryOperatorLessThanOrEqual","BinaryOperatorGreaterThanOrEqual"],"default":"BinaryOperatorAnd"},"v2UnaryExpression":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/v2UnaryOperator"},"inner":{"$ref":"#/components/schemas/v2Expression"}}},"v2UnaryOperator":{"type":"string","enum":["UnaryOperatorNot","UnaryOperatorExists"],"default":"UnaryOperatorNot"},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2TriggerInstanceStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2TriggerInstanceState"},"state_category":{"$ref":"#/components/schemas/v2TriggerInstanceStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"}},"title":"Status information for a BookConnection"},"v2TriggerInstanceState":{"type":"string","enum":["TRIGGER_INSTANCE_STATE_PENDING","TRIGGER_INSTANCE_STATE_READY","TRIGGER_INSTANCE_STATE_FAILED","TRIGGER_INSTANCE_STATE_UNKNOWN"],"default":"TRIGGER_INSTANCE_STATE_PENDING","title":"Possible phases for a TriggerInstance (Pending, Ready, Failed, Unknown)"},"v2TriggerInstanceStateCategory":{"type":"string","enum":["TRIGGER_INSTANCE_STATE_CATEGORY_WARNING","TRIGGER_INSTANCE_STATE_CATEGORY_READY","TRIGGER_INSTANCE_STATE_CATEGORY_FAILED"],"default":"TRIGGER_INSTANCE_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"AddWorkspaceBookConnectionTriggerInstanceBody":{"type":"object","properties":{"trigger_id":{"type":"string","title":"The name of the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configuration parameters for the trigger"},"filter_expression":{"$ref":"#/components/schemas/v2Expression"},"name":{"type":"string","title":"The name of the trigger instance"}}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/books/{book_name}/{book_version}/connections/{connection_id}/triggers":{"post":{"summary":"Create Trigger Instance","operationId":"AddWorkspaceBookConnectionTriggerInstance","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2AddWorkspaceBookConnectionTriggerInstanceResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"book_version","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddWorkspaceBookConnectionTriggerInstanceBody"}}},"required":true},"tags":["Books"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/triggers/{trigger\_instance\_id}/automations > Set Trigger Automations ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2SetAutomationsForTriggerInstanceResponse":{"type":"object","properties":{"trigger_instance":{"$ref":"#/components/schemas/v2TriggerInstance"}}},"v2TriggerInstance":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger instance"},"name":{"type":"string","title":"The name of the trigger instance"},"reference":{"type":"string","title":"The reference of the trigger instance"},"book_name":{"type":"string","title":"The name of the book"},"connection_id":{"type":"string","title":"The identifier of the book connection"},"trigger_id":{"type":"string","title":"The name of the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configuration parameters for the trigger"},"endpoint":{"type":"string","title":"The endpoint of the trigger instance"},"automation_ids":{"type":"array","items":{"type":"string"},"title":"Automation IDs"},"workspace_id":{"type":"string","title":"Workspace ID"},"organization_id":{"type":"string","title":"Organization ID"},"filter_expression":{"$ref":"#/components/schemas/v2Expression"},"status":{"$ref":"#/components/schemas/v2TriggerInstanceStatus"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2Expression":{"type":"object","properties":{"binary_expression":{"$ref":"#/components/schemas/v2BinaryExpression"},"unary_expression":{"$ref":"#/components/schemas/v2UnaryExpression"},"value_expression":{"$ref":"#/components/schemas/bdkV2Value"},"noun_phrases_expression":{"$ref":"#/components/schemas/v2NounPhrases"}}},"v2BinaryExpression":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/v2BinaryOperator"},"left":{"$ref":"#/components/schemas/v2Expression"},"right":{"$ref":"#/components/schemas/v2Expression"}}},"v2BinaryOperator":{"type":"string","enum":["BinaryOperatorAnd","BinaryOperatorOr","BinaryOperatorEquals","BinaryOperatorNotEquals","BinaryOperatorIn","BinaryOperatorHas","BinaryOperatorLessThan","BinaryOperatorGreaterThan","BinaryOperatorLessThanOrEqual","BinaryOperatorGreaterThanOrEqual"],"default":"BinaryOperatorAnd"},"v2UnaryExpression":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/v2UnaryOperator"},"inner":{"$ref":"#/components/schemas/v2Expression"}}},"v2UnaryOperator":{"type":"string","enum":["UnaryOperatorNot","UnaryOperatorExists"],"default":"UnaryOperatorNot"},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2TriggerInstanceStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2TriggerInstanceState"},"state_category":{"$ref":"#/components/schemas/v2TriggerInstanceStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"}},"title":"Status information for a BookConnection"},"v2TriggerInstanceState":{"type":"string","enum":["TRIGGER_INSTANCE_STATE_PENDING","TRIGGER_INSTANCE_STATE_READY","TRIGGER_INSTANCE_STATE_FAILED","TRIGGER_INSTANCE_STATE_UNKNOWN"],"default":"TRIGGER_INSTANCE_STATE_PENDING","title":"Possible phases for a TriggerInstance (Pending, Ready, Failed, Unknown)"},"v2TriggerInstanceStateCategory":{"type":"string","enum":["TRIGGER_INSTANCE_STATE_CATEGORY_WARNING","TRIGGER_INSTANCE_STATE_CATEGORY_READY","TRIGGER_INSTANCE_STATE_CATEGORY_FAILED"],"default":"TRIGGER_INSTANCE_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"SetAutomationsForTriggerInstanceBody":{"type":"object","properties":{"automation_ids":{"type":"array","items":{"type":"string"},"title":"The identifiers of the automations to attach to the trigger instance"},"connection_id":{"type":"string","title":"The id of the book connection"}}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/triggers/{trigger_instance_id}/automations":{"post":{"summary":"Set Trigger Automations","operationId":"SetAutomationsForTriggerInstance","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2SetAutomationsForTriggerInstanceResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"trigger_instance_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAutomationsForTriggerInstanceBody"}}},"required":true},"tags":["Books"]}}}} ``` ## DELETE /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/connections/{connection\_id}/triggers/{trigger\_instance\_id} > Delete Trigger Instance ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RemoveWorkspaceBookConnectionTriggerInstanceResponse":{"type":"object"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/triggers/{trigger_instance_id}":{"delete":{"summary":"Delete Trigger Instance","operationId":"RemoveWorkspaceBookConnectionTriggerInstance","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RemoveWorkspaceBookConnectionTriggerInstanceResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"trigger_instance_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/triggers > View Trigger Instances ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveWorkspaceTriggerInstancesResponse":{"type":"object","properties":{"trigger_instances":{"type":"array","items":{"$ref":"#/components/schemas/v2TriggerInstance"},"title":"The trigger instances"}}},"v2TriggerInstance":{"type":"object","properties":{"id":{"type":"string","title":"The identifier of the trigger instance"},"name":{"type":"string","title":"The name of the trigger instance"},"reference":{"type":"string","title":"The reference of the trigger instance"},"book_name":{"type":"string","title":"The name of the book"},"connection_id":{"type":"string","title":"The identifier of the book connection"},"trigger_id":{"type":"string","title":"The name of the trigger"},"configuration":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/bdkV2Value"},"title":"Configuration parameters for the trigger"},"endpoint":{"type":"string","title":"The endpoint of the trigger instance"},"automation_ids":{"type":"array","items":{"type":"string"},"title":"Automation IDs"},"workspace_id":{"type":"string","title":"Workspace ID"},"organization_id":{"type":"string","title":"Organization ID"},"filter_expression":{"$ref":"#/components/schemas/v2Expression"},"status":{"$ref":"#/components/schemas/v2TriggerInstanceStatus"}}},"bdkV2Value":{"type":"object","properties":{"null_value":{"type":"string"},"conceptual_value":{"$ref":"#/components/schemas/v2NounPhrase"},"text_value":{"type":"string","title":"deprecated: use offloadable_text_value (15) for new code"},"number_value":{"type":"number","format":"double"},"boolean_value":{"type":"boolean"},"datetime_value":{"type":"string","format":"date-time"},"date_value":{"$ref":"#/components/schemas/v2Date"},"time_value":{"$ref":"#/components/schemas/v2Time"},"file_value":{"$ref":"#/components/schemas/v2FileValue"},"dictionary_value":{"$ref":"#/components/schemas/v2DictionaryValue"},"list_value":{"$ref":"#/components/schemas/bdkV2ListValue"},"opaque_value":{"$ref":"#/components/schemas/v2OpaqueValue"},"table_value":{"$ref":"#/components/schemas/v2TableValue"},"sensitive_value":{"$ref":"#/components/schemas/v2SensitiveValue"},"offloadable_text_value":{"$ref":"#/components/schemas/v2OffloadableTextValue"},"offloadable_dictionary_value":{"$ref":"#/components/schemas/v2OffloadableDictionaryValue"},"offloadable_list_value":{"$ref":"#/components/schemas/v2OffloadableListValue"}},"title":"A union of all possible values"},"v2NounPhrase":{"type":"object","properties":{"modifiers":{"type":"array","items":{"type":"string"},"title":"Optional adjectives attached to the noun"},"head":{"type":"string","title":"Noun of the phrase"}}},"v2Date":{"type":"object","properties":{"year":{"type":"integer","format":"int32","title":"Year of the date"},"month":{"type":"integer","format":"int32","title":"Month of a year"},"day":{"type":"integer","format":"int32","title":"Day of a month"}}},"v2Time":{"type":"object","properties":{"hours":{"type":"integer","format":"int32","title":"Hours of day"},"minutes":{"type":"integer","format":"int32","title":"Minutes of hour of day"},"seconds":{"type":"integer","format":"int32","title":"Seconds of minutes of the time"},"nanos":{"type":"integer","format":"int32","title":"Fractions of seconds in nanoseconds"}}},"v2FileValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2File"}},"title":"A file value represents a file that can be either inline or remote"},"v2File":{"type":"object","properties":{"file_name":{"type":"string","title":"The name of the file"},"content":{"type":"string","format":"byte","title":"Content of the file as a byte stream"}}},"v2DictionaryValue":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/v2DictionaryValueField"},"title":"All the fields alongside their values in the dictionary"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the dictionary"}},"title":"Value to be used when the type is dictionary"},"v2DictionaryValueField":{"type":"object","properties":{"key":{"type":"string"},"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"Each key-value pair inside a dictionary"},"bdkV2ListValue":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"},"title":"All the values inside the list"}},"title":"A collection of values"},"v2OpaqueValue":{"type":"object","properties":{"content":{"type":"string","format":"byte","title":"Content of the opaque value"},"is_a":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"},"title":"Is a replationships for the opaque"}}},"v2TableValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2Table"}},"title":"A table that is represented remote as an URL to a file that is Feather-formatted\nor inline via the Table message"},"v2Table":{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/v2Column"}}},"description":"A table is a column-oriented structure. All the values inside each column must\nbe of equal length."},"v2Column":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/bdkV2Value"}},"name":{"type":"string"}}},"v2SensitiveValue":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/bdkV2Value"}},"title":"A sensitive value is any value marked as sensitive (to prevent exposure)"},"v2OffloadableTextValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"type":"string"}},"title":"A text value that can be either inline or stored remotely"},"v2OffloadableDictionaryValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/v2DictionaryValue"}},"title":"A dictionary value that can be either inline or stored remotely"},"v2OffloadableListValue":{"type":"object","properties":{"remote":{"type":"string"},"inline":{"$ref":"#/components/schemas/bdkV2ListValue"}},"title":"A list value that can be either inline or stored remotely"},"v2Expression":{"type":"object","properties":{"binary_expression":{"$ref":"#/components/schemas/v2BinaryExpression"},"unary_expression":{"$ref":"#/components/schemas/v2UnaryExpression"},"value_expression":{"$ref":"#/components/schemas/bdkV2Value"},"noun_phrases_expression":{"$ref":"#/components/schemas/v2NounPhrases"}}},"v2BinaryExpression":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/v2BinaryOperator"},"left":{"$ref":"#/components/schemas/v2Expression"},"right":{"$ref":"#/components/schemas/v2Expression"}}},"v2BinaryOperator":{"type":"string","enum":["BinaryOperatorAnd","BinaryOperatorOr","BinaryOperatorEquals","BinaryOperatorNotEquals","BinaryOperatorIn","BinaryOperatorHas","BinaryOperatorLessThan","BinaryOperatorGreaterThan","BinaryOperatorLessThanOrEqual","BinaryOperatorGreaterThanOrEqual"],"default":"BinaryOperatorAnd"},"v2UnaryExpression":{"type":"object","properties":{"operator":{"$ref":"#/components/schemas/v2UnaryOperator"},"inner":{"$ref":"#/components/schemas/v2Expression"}}},"v2UnaryOperator":{"type":"string","enum":["UnaryOperatorNot","UnaryOperatorExists"],"default":"UnaryOperatorNot"},"v2NounPhrases":{"type":"object","properties":{"noun_phrases":{"type":"array","items":{"$ref":"#/components/schemas/v2NounPhrase"}}}},"v2TriggerInstanceStatus":{"type":"object","properties":{"state":{"$ref":"#/components/schemas/v2TriggerInstanceState"},"state_category":{"$ref":"#/components/schemas/v2TriggerInstanceStateCategory"},"reason":{"type":"string","title":"Human-readable message providing additional details about the current state"},"last_updated":{"type":"string","title":"RFC 3339 timestamp of when the status was last updated"}},"title":"Status information for a BookConnection"},"v2TriggerInstanceState":{"type":"string","enum":["TRIGGER_INSTANCE_STATE_PENDING","TRIGGER_INSTANCE_STATE_READY","TRIGGER_INSTANCE_STATE_FAILED","TRIGGER_INSTANCE_STATE_UNKNOWN"],"default":"TRIGGER_INSTANCE_STATE_PENDING","title":"Possible phases for a TriggerInstance (Pending, Ready, Failed, Unknown)"},"v2TriggerInstanceStateCategory":{"type":"string","enum":["TRIGGER_INSTANCE_STATE_CATEGORY_WARNING","TRIGGER_INSTANCE_STATE_CATEGORY_READY","TRIGGER_INSTANCE_STATE_CATEGORY_FAILED"],"default":"TRIGGER_INSTANCE_STATE_CATEGORY_WARNING","title":"The category/level of the connection state"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/triggers":{"get":{"summary":"View Trigger Instances","operationId":"ListWorkspaceTriggerInstances","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveWorkspaceTriggerInstancesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"AIP-160 Filter expression\nhttps://google.aip.dev/160","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` ## View Connection User Info > This endpoint returns information about the user (email, username and other extra attributes) from\ > a book that has already been connected. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Books","description":"Browse and search books, concepts, procedures, connections, and triggers."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v2RetrieveUserInfoResponse":{"type":"object","properties":{"user_info":{"$ref":"#/components/schemas/v2UserInfo"}},"title":"The response to a retrieve user info request"},"v2UserInfo":{"type":"object","properties":{"email":{"type":"string","title":"The email of the user"},"username":{"type":"string","title":"The username of the user"},"other_attributes":{"type":"object","additionalProperties":{"type":"string"},"title":"A map with other extra attributes the user may have"}}},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/connections/{connection_id}/user-info":{"get":{"summary":"View Connection User Info","description":"This endpoint returns information about the user (email, username and other extra attributes) from\n a book that has already been connected.","operationId":"GetWorkspaceBookConnectionUserInfo","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v2RetrieveUserInfoResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Books"]}}}} ``` # Files Upload, download, and manage files. ## Upload File > Upload a file scoped to a specific workspace. The file's lifetime is tied\ > to the organization. This is the preferred endpoint for new file uploads. ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1UploadFileResponse":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/v1FileMetadata"}},"title":"Response after uploading a file\nFor HTTP/REST: Returns JSON with metadata\nHTTP Status: 201 Created with Location header pointing to the created resource"},"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"apiHttpBody":{"type":"object","properties":{"content_type":{"type":"string","description":"The HTTP Content-Type header value specifying the content type of the body."},"data":{"type":"string","format":"byte","description":"The HTTP request/response body as raw binary."},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"},"description":"Application specific response metadata. Must be set in the first response\nfor streaming APIs."}},"description":"Message that represents an arbitrary HTTP body. It should only be used for\npayload formats that can't be represented as JSON, such as raw binary or\nan HTML page.\n\n\nThis message can be used both in streaming and non-streaming API methods in\nthe request as well as the response.\n\nIt can be used as a top-level request field, which is convenient if one\nwants to extract parameters from either the URL or HTTP template into the\nrequest fields and also want access to the raw HTTP body.\n\nExample:\n\n message GetResourceRequest {\n // A unique request id.\n string request_id = 1;\n\n // The raw HTTP body is bound to this field.\n google.api.HttpBody http_body = 2;\n\n }\n\n service ResourceService {\n rpc GetResource(GetResourceRequest)\n returns (google.api.HttpBody);\n rpc UpdateResource(google.api.HttpBody)\n returns (google.protobuf.Empty);\n\n }\n\nExample with streaming methods:\n\n service CaldavService {\n rpc GetCalendar(stream google.api.HttpBody)\n returns (stream google.api.HttpBody);\n rpc UpdateCalendar(stream google.api.HttpBody)\n returns (stream google.api.HttpBody);\n\n }\n\nUse of this type only changes how the request and response bodies are\nhandled, all other features will continue to work unchanged."}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files:upload":{"post":{"summary":"Upload File","description":"Upload a file scoped to a specific workspace. The file's lifetime is tied\nto the organization. This is the preferred endpoint for new file uploads.","operationId":"UploadFile","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1UploadFileResponse"}}}},"201":{"description":"File uploaded successfully","headers":{"Location":{"description":"URL of the created file resource","schema":{"type":"string"}}},"content":{"application/json":{"schema":{}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/apiHttpBody"}}},"description":"Raw HTTP body containing multipart/form-data","required":true},"tags":["Files"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}:download > Download File ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:download":{"get":{"summary":"Download File","operationId":"DownloadFile","responses":{"200":{"description":"File content","headers":{"Content-Disposition":{"description":"Attachment with filename","schema":{"type":"string"}},"Content-Length":{"description":"File size in bytes","schema":{"type":"string"}},"Content-Type":{"description":"MIME type of the file","schema":{"type":"string"}}},"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"An unexpected error response.","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}/metadata > Get File Metadata ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1FileMetadata":{"type":"object","properties":{"name":{"type":"string","title":"The resource name of the file (server-generated)","readOnly":true},"filename":{"type":"string","title":"Filename of the file (e.g., \"document.pdf\")"},"mime_type":{"type":"string","title":"MIME type of the file (server-detected for security)","readOnly":true},"size_bytes":{"type":"string","format":"int64","title":"Size of the file in bytes (server-calculated)","readOnly":true},"create_time":{"type":"string","format":"date-time","title":"Timestamp when the file was created","readOnly":true}},"title":"File metadata resource in the Bishop system","required":["filename"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}/metadata":{"get":{"summary":"Get File Metadata","operationId":"GetFileMetadata","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1FileMetadata"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}} ``` ## DELETE /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file} > Delete File ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}":{"delete":{"summary":"Delete File","operationId":"DeleteFile","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Files"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files:generateUploadUrl > Generate Upload Url ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateUploadUrlResponse":{"type":"object","properties":{"upload_uri":{"type":"string","title":"Presigned upload URI"}},"title":"Response with presigned upload URL"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"GenerateUploadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","title":"Optional expiration duration"}},"description":"If no expiration duration is provided, the default is 1 hour.","title":"Request to generate presigned upload URL"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files:generateUploadUrl":{"post":{"summary":"Generate Upload Url","operationId":"GenerateUploadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateUploadUrlResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateUploadUrlBody"}}},"required":true},"tags":["Files"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/files/{file}:generateDownloadUrl > Generate Download Url ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Files","description":"Upload, download, and manage files."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GenerateDownloadUrlResponse":{"type":"object","properties":{"download_uri":{"type":"string","title":"Presigned download URI"}},"title":"Response with presigned download URL"},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"GenerateDownloadUrlBody":{"type":"object","properties":{"expire_duration":{"type":"string","title":"Optional expiration duration"}},"description":"If no expiration duration is provided, the default is 1 hour.","title":"Request to generate presigned download URL"}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/files/{file}:generateDownloadUrl":{"post":{"summary":"Generate Download Url","operationId":"GenerateDownloadUrl","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GenerateDownloadUrlResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"file","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDownloadUrlBody"}}},"required":true},"tags":["Files"]}}}} ``` # Exceptions Track exceptions, view analytics, manage agent events, and access troubleshooting guides. ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptions/{exception\_id} > Get Exception ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Exception":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the exception.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"},"run":{"type":"string","title":"The run in which the exception occurred. The run must belong\nto the same workspace as the exception.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"location":{"$ref":"#/components/schemas/commonV1Location"},"message":{"type":"string","description":"The exception message generated by the interpreter."},"create_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was last updated.","readOnly":true},"state":{"$ref":"#/components/schemas/v1ExceptionState"},"automation":{"type":"string","title":"The automation that the exception belongs to. The automation of an exception\nis the automation that the run belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the exception. Generated by the exception service.\nRecently created exceptions may not yet have a description.","readOnly":true},"group":{"type":"string","description":"Groups are used to categorize exceptions\nCurrently support static groups: \"missing_values\", \"user_system_error\", \"internal_error\"\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nIn future, we may support dynamic groups.\nEmpty string means the exception is not grouped."},"resolution_guide_entry":{"type":"string","title":"The guide entry that was used to automatically resolve this exception.\nSet when the exception service successfully applies\na guide entry to resolve the exception i.e exception.state should be RESOLVED if this field is set.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}","readOnly":true},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"execution_id":{"type":"string","title":"The execution ID within the run where this exception occurred.\nUsed to differentiate exceptions at the same location with the same message.\nExample: \"exec_123abc\" or a UUID"},"extra":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra information about the exception."},"assignee":{"type":"string","title":"The user assigned to resolve this exception.\nFormat: users/{user}"},"resolver":{"type":"string","description":"The entity that resolved this exception.\nCan be either a user (for manual resolutions) or an agent (for automatic resolutions).\nFormat: users/{user} or agents/{agent}\nNote: No resource_reference is specified to avoid service dependencies and to support\nmultiple resource types in a single field."}},"description":"An exception that occurred during an automation run.\nExceptions are raised by the interpreter and are analogous to Python exceptions.\nHowever, the Kognitos platform provides various mechanisms to resolve an\nexception and then resume the run.\nAutomation runs are important business processes for our users, so the expectation\nis that every exception needs to be resolved even if the resolution involves manual steps\nor abandoning the automation run.","required":["run","location","message"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1ExceptionState":{"type":"string","enum":["EXCEPTION_STATE_UNSPECIFIED","EXCEPTION_STATE_PENDING","EXCEPTION_STATE_RESOLVED","EXCEPTION_STATE_ARCHIVED"],"default":"EXCEPTION_STATE_UNSPECIFIED","description":"The state of an exception.\n\n - EXCEPTION_STATE_UNSPECIFIED: The state is not specified.\n - EXCEPTION_STATE_PENDING: The exception is pending resolution.\nThis is the initial state when an exception is created.\nTransitions:\nOn creation --> PENDING\nPENDING --> RESOLVED: Exception successfully resolved (run can continue)\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\n - EXCEPTION_STATE_RESOLVED: The exception has been resolved.\nRESOLVED is a terminal state. Resolved exceptions are retained for historical records\nTransitions:\nPENDING --> RESOLVED: Exception resolved (run can continue)\n - EXCEPTION_STATE_ARCHIVED: The exception has been archived.\nArchived exceptions are retained for historical records and audit purposes.\nTransitions:\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\nARCHIVED --> PENDING: Exception unarchived (run can continue)"},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}":{"get":{"summary":"Get Exception","operationId":"GetException","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Exception"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"exception_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptions > List Exceptions ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListExceptionsResponse":{"type":"object","properties":{"exceptions":{"type":"array","items":{"$ref":"#/components/schemas/v1Exception"},"description":"The exceptions."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListExceptions`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of exceptions that match the given filter across all pages.\nThis count is not affected by page_size or page_token parameters."}},"description":"A response to a list exceptions request."},"v1Exception":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the exception.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"},"run":{"type":"string","title":"The run in which the exception occurred. The run must belong\nto the same workspace as the exception.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}/runs/{run}"},"location":{"$ref":"#/components/schemas/commonV1Location"},"message":{"type":"string","description":"The exception message generated by the interpreter."},"create_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp of when the exception was last updated.","readOnly":true},"state":{"$ref":"#/components/schemas/v1ExceptionState"},"automation":{"type":"string","title":"The automation that the exception belongs to. The automation of an exception\nis the automation that the run belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"description":{"type":"string","description":"A human-friendly description of the exception. Generated by the exception service.\nRecently created exceptions may not yet have a description.","readOnly":true},"group":{"type":"string","description":"Groups are used to categorize exceptions\nCurrently support static groups: \"missing_values\", \"user_system_error\", \"internal_error\"\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nIn future, we may support dynamic groups.\nEmpty string means the exception is not grouped."},"resolution_guide_entry":{"type":"string","title":"The guide entry that was used to automatically resolve this exception.\nSet when the exception service successfully applies\na guide entry to resolve the exception i.e exception.state should be RESOLVED if this field is set.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}","readOnly":true},"stage":{"$ref":"#/components/schemas/v1AutomationStage"},"execution_id":{"type":"string","title":"The execution ID within the run where this exception occurred.\nUsed to differentiate exceptions at the same location with the same message.\nExample: \"exec_123abc\" or a UUID"},"extra":{"type":"object","additionalProperties":{"type":"string"},"description":"Extra information about the exception."},"assignee":{"type":"string","title":"The user assigned to resolve this exception.\nFormat: users/{user}"},"resolver":{"type":"string","description":"The entity that resolved this exception.\nCan be either a user (for manual resolutions) or an agent (for automatic resolutions).\nFormat: users/{user} or agents/{agent}\nNote: No resource_reference is specified to avoid service dependencies and to support\nmultiple resource types in a single field."}},"description":"An exception that occurred during an automation run.\nExceptions are raised by the interpreter and are analogous to Python exceptions.\nHowever, the Kognitos platform provides various mechanisms to resolve an\nexception and then resume the run.\nAutomation runs are important business processes for our users, so the expectation\nis that every exception needs to be resolved even if the resolution involves manual steps\nor abandoning the automation run.","required":["run","location","message"]},"commonV1Location":{"type":"object","properties":{"start_byte":{"type":"string","format":"int64","title":"Starting Byte of the span, It will be zero-based"},"end_byte":{"type":"string","format":"int64","title":"Ending Byte(exclusive) of the span, It will be zero-based"}},"description":"Location represents a generic span within some underlying content.\nIt specifies the starting byte offset and the ending byte offset (exclusive) of the span.\nThis can be used for pointing to regions in files, buffers, logs, messages,\nor any other byte-addressable resource."},"v1ExceptionState":{"type":"string","enum":["EXCEPTION_STATE_UNSPECIFIED","EXCEPTION_STATE_PENDING","EXCEPTION_STATE_RESOLVED","EXCEPTION_STATE_ARCHIVED"],"default":"EXCEPTION_STATE_UNSPECIFIED","description":"The state of an exception.\n\n - EXCEPTION_STATE_UNSPECIFIED: The state is not specified.\n - EXCEPTION_STATE_PENDING: The exception is pending resolution.\nThis is the initial state when an exception is created.\nTransitions:\nOn creation --> PENDING\nPENDING --> RESOLVED: Exception successfully resolved (run can continue)\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\n - EXCEPTION_STATE_RESOLVED: The exception has been resolved.\nRESOLVED is a terminal state. Resolved exceptions are retained for historical records\nTransitions:\nPENDING --> RESOLVED: Exception resolved (run can continue)\n - EXCEPTION_STATE_ARCHIVED: The exception has been archived.\nArchived exceptions are retained for historical records and audit purposes.\nTransitions:\nPENDING --> ARCHIVED: Exception archived without resolution (run abandoned)\nARCHIVED --> PENDING: Exception unarchived (run can continue)"},"v1AutomationStage":{"type":"string","enum":["AUTOMATION_STAGE_UNSPECIFIED","AUTOMATION_STAGE_DRAFT","AUTOMATION_STAGE_PUBLISHED"],"default":"AUTOMATION_STAGE_UNSPECIFIED","description":"AutomationStage represents the publication stage of an automation.\nThis enum is shared across services that manage or execute automations.\n\n - AUTOMATION_STAGE_UNSPECIFIED: Automation stage is not specified.\n - AUTOMATION_STAGE_DRAFT: Automation is in draft stage and can be modified.\n - AUTOMATION_STAGE_PUBLISHED: Automation is published and immutable, ready for execution."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions":{"get":{"summary":"List Exceptions","operationId":"ListExceptions","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListExceptionsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of exceptions to return. The service may return fewer than this value.\nIf unspecified, at most 50 exceptions will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListExceptions` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListExceptions` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"skip","description":"The number of exceptions to skip before returning results.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"filter","description":"The filter to apply to the list of exceptions.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- state: Exception state (PENDING, RESOLVED, ARCHIVED)\n- automation: Automation ID (exact match only)\n- create_time: Exception creation timestamp (ISO 8601 format)\n- group: Exception group (exact match only)\n - Use group = \"value\" to match a specific group\n - Use group = \"\" to match exceptions with no group assigned (ungrouped)\n- run: Run ID (exact match only)\n - Use run = \"run1_id\" to match a specific run\n - Use run = \"run1_id OR run2_id\" to match multiple runs\n\nSupported Operators:\n- Comparison: =, !=, <, <=, >, >=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n\nState Values:\n- PENDING or EXCEPTION_STATE_PENDING\n- RESOLVED or EXCEPTION_STATE_RESOLVED\n- ARCHIVED or EXCEPTION_STATE_ARCHIVED\n\nTimestamp Format:\n- ISO 8601 with Z suffix: \"2025-01-01T00:00:00Z\"\n- ISO 8601 with offset: \"2025-01-01T00:00:00+00:00\"\n\nExample Filters:\n- \"state = PENDING\" - List only pending exceptions\n- \"state != RESOLVED\" - List all non-resolved exceptions\n- \"automation = my-automation-id\" - List exceptions for a specific automation\n- \"state = PENDING AND automation = my-automation-id\" - Pending exceptions for an automation\n- \"state = PENDING OR state = ARCHIVED\" - Pending or archived exceptions\n- \"NOT state = RESOLVED\" - All non-resolved exceptions\n- \"create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Exceptions created after Jan 1, 2025\n- \"create_time >= \\\"2025-01-01T00:00:00Z\\\" AND create_time < \\\"2025-02-01T00:00:00Z\\\"\" - January 2025 exceptions\n- \"(state = PENDING OR state = ARCHIVED) AND create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Recent unresolved exceptions\n- \"group = \\\"missing_values\\\"\" - List exceptions in exactly the missing_values group\n- \"group = \\\"missing_values\\\" OR group = \\\"user_system_error\\\"\" - List exceptions in multiple groups\n- \"group = \\\"\\\"\" - List ungrouped exceptions (no group assigned)\n- \"state = PENDING AND group = \\\"\\\"\" - List pending ungrouped exceptions\n- \"group != \\\"\\\"\" - List all exceptions that have a group assigned (any group)\n- \"run = run1_id OR run = run2_id\" - List exceptions for multiple runs\n- \"run = run1_id\" - List exceptions for a specific run","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events > List Events ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/v1Event"},"description":"The events in the conversation thread, ordered by creation time (newest first)."},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListEvents`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of events in the conversation thread across all pages.\nThis count is not affected by page_size or page_token parameters."}},"description":"A response to a list events request."},"v1Event":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the event.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}"},"state":{"$ref":"#/components/schemas/v1EventState"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the event was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the event was last updated.","readOnly":true},"user_message":{"$ref":"#/components/schemas/v1UserMessage"},"agent_message":{"$ref":"#/components/schemas/v1AgentMessage"},"tool_call_request":{"$ref":"#/components/schemas/v1ToolCallRequest"},"tool_call_result":{"$ref":"#/components/schemas/v1ToolCallResult"},"thinking":{"$ref":"#/components/schemas/v1Thinking"},"system_message":{"$ref":"#/components/schemas/v1SystemMessage"},"completion_response":{"$ref":"#/components/schemas/v1CompletionResponse"},"exception":{"type":"string","title":"An optional exception resource name that the event belongs to.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"An event in a run conversation thread about an exception.\nEvents form a timeline of interactions between users, AI agents, and the system."},"v1EventState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_STREAMING","STATE_COMPLETE"],"default":"STATE_UNSPECIFIED","description":"The state of an event.\n\n - STATE_UNSPECIFIED: The state is not specified. This value is not used.\n - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.\n - STATE_COMPLETE: The event fields are done being generated."},"v1UserMessage":{"type":"object","properties":{"user":{"type":"string","title":"The user who authored the message.\nFormat: users/{user}"},"content":{"type":"string","description":"Simple text content."},"content_list":{"$ref":"#/components/schemas/v1InputContentList"}},"description":"A message from a user."},"v1InputContentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1InputContent"},"description":"The list of input content items."}},"description":"A list of input content items (can contain text and/or binary content).","required":["items"]},"v1InputContent":{"type":"object","properties":{"text":{"type":"string","description":"Text content."},"file":{"$ref":"#/components/schemas/v1FileInputContent"}},"description":"InputContent represents a single input item that can be text or binary."},"v1FileInputContent":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1FileContent"}},"description":"FileInputContent represents a file that can be either stored inline or referenced remotely."},"v1FileContent":{"type":"object","properties":{"mime_type":{"type":"string","description":"The MIME type of the file."},"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"filename":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"FileContent represents a file with its name and binary content.","required":["mime_type","content"]},"v1AgentMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A message from the AI agent."},"v1ToolCallRequest":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"display_name":{"type":"string","description":"The display name of the tool being called.","readOnly":true},"input":{"type":"string","description":"The input arguments passed to the tool. Contains arbitrary data in a tool-specific format\nthat the agent generates for the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call arguments.","readOnly":true}},"description":"A tool call request made by the AI agent."},"v1ToolCallResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"result":{"type":"string","description":"The result of the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call result.","readOnly":true}},"description":"A tool call result returned by the tool."},"v1Thinking":{"type":"object","properties":{"content":{"type":"string","description":"The thinking content. CommonMark(GFM) formatted.","readOnly":true}},"description":"Thinking or reasoning by the AI agent."},"v1SystemMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the system message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A system-generated message."},"v1CompletionResponse":{"type":"object","properties":{"content":{"type":"string","description":"Final content if successful."},"error":{"type":"string","description":"Error description if the request failed."}},"description":"Terminal completion for the agent workflow."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events":{"get":{"summary":"List Events","operationId":"ListEvents","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListEventsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of events to return. The service may return fewer than this value.\nIf unspecified, at most 50 events will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListEvents` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListEvents` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"filter","description":"The filter to apply to the list of events.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- exception: Exception Id\n\nSupported Operators:\n- Comparison: =, !=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n\nExample Filters:\n- \"exception = \\\"exc-123\\\"\" - Events for a specific exception\n- \"exception = \\\"exc-123\\\" OR exception = \\\"exc-456\\\"\" - Events for multiple exceptions","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events > Create Event ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Event":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the event.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}"},"state":{"$ref":"#/components/schemas/v1EventState"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the event was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the event was last updated.","readOnly":true},"user_message":{"$ref":"#/components/schemas/v1UserMessage"},"agent_message":{"$ref":"#/components/schemas/v1AgentMessage"},"tool_call_request":{"$ref":"#/components/schemas/v1ToolCallRequest"},"tool_call_result":{"$ref":"#/components/schemas/v1ToolCallResult"},"thinking":{"$ref":"#/components/schemas/v1Thinking"},"system_message":{"$ref":"#/components/schemas/v1SystemMessage"},"completion_response":{"$ref":"#/components/schemas/v1CompletionResponse"},"exception":{"type":"string","title":"An optional exception resource name that the event belongs to.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"An event in a run conversation thread about an exception.\nEvents form a timeline of interactions between users, AI agents, and the system."},"v1EventState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_STREAMING","STATE_COMPLETE"],"default":"STATE_UNSPECIFIED","description":"The state of an event.\n\n - STATE_UNSPECIFIED: The state is not specified. This value is not used.\n - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.\n - STATE_COMPLETE: The event fields are done being generated."},"v1UserMessage":{"type":"object","properties":{"user":{"type":"string","title":"The user who authored the message.\nFormat: users/{user}"},"content":{"type":"string","description":"Simple text content."},"content_list":{"$ref":"#/components/schemas/v1InputContentList"}},"description":"A message from a user."},"v1InputContentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1InputContent"},"description":"The list of input content items."}},"description":"A list of input content items (can contain text and/or binary content).","required":["items"]},"v1InputContent":{"type":"object","properties":{"text":{"type":"string","description":"Text content."},"file":{"$ref":"#/components/schemas/v1FileInputContent"}},"description":"InputContent represents a single input item that can be text or binary."},"v1FileInputContent":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1FileContent"}},"description":"FileInputContent represents a file that can be either stored inline or referenced remotely."},"v1FileContent":{"type":"object","properties":{"mime_type":{"type":"string","description":"The MIME type of the file."},"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"filename":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"FileContent represents a file with its name and binary content.","required":["mime_type","content"]},"v1AgentMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A message from the AI agent."},"v1ToolCallRequest":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"display_name":{"type":"string","description":"The display name of the tool being called.","readOnly":true},"input":{"type":"string","description":"The input arguments passed to the tool. Contains arbitrary data in a tool-specific format\nthat the agent generates for the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call arguments.","readOnly":true}},"description":"A tool call request made by the AI agent."},"v1ToolCallResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"result":{"type":"string","description":"The result of the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call result.","readOnly":true}},"description":"A tool call result returned by the tool."},"v1Thinking":{"type":"object","properties":{"content":{"type":"string","description":"The thinking content. CommonMark(GFM) formatted.","readOnly":true}},"description":"Thinking or reasoning by the AI agent."},"v1SystemMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the system message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A system-generated message."},"v1CompletionResponse":{"type":"object","properties":{"content":{"type":"string","description":"Final content if successful."},"error":{"type":"string","description":"Error description if the request failed."}},"description":"Terminal completion for the agent workflow."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events":{"post":{"summary":"Create Event","operationId":"CreateEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Event"}}},"description":"The event to create.\nIMPORTANT: Only user_message can be set when creating an event. The API will reject\nrequests that attempt to create events with agent_message, tool_call, thinking, or\nsystem_message set. These event types are automatically created by the system.","required":true},"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events/{event\_id} > Get Event ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1Event":{"type":"object","properties":{"name":{"type":"string","title":"The full resource name of the event.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}"},"state":{"$ref":"#/components/schemas/v1EventState"},"create_time":{"type":"string","format":"date-time","description":"The timestamp when the event was created.","readOnly":true},"update_time":{"type":"string","format":"date-time","description":"The timestamp when the event was last updated.","readOnly":true},"user_message":{"$ref":"#/components/schemas/v1UserMessage"},"agent_message":{"$ref":"#/components/schemas/v1AgentMessage"},"tool_call_request":{"$ref":"#/components/schemas/v1ToolCallRequest"},"tool_call_result":{"$ref":"#/components/schemas/v1ToolCallResult"},"thinking":{"$ref":"#/components/schemas/v1Thinking"},"system_message":{"$ref":"#/components/schemas/v1SystemMessage"},"completion_response":{"$ref":"#/components/schemas/v1CompletionResponse"},"exception":{"type":"string","title":"An optional exception resource name that the event belongs to.\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptions/{exception_id}"}},"description":"An event in a run conversation thread about an exception.\nEvents form a timeline of interactions between users, AI agents, and the system."},"v1EventState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_STREAMING","STATE_COMPLETE"],"default":"STATE_UNSPECIFIED","description":"The state of an event.\n\n - STATE_UNSPECIFIED: The state is not specified. This value is not used.\n - STATE_STREAMING: The event fields are being generated by the AI agent. event_data fields may have partial values.\n - STATE_COMPLETE: The event fields are done being generated."},"v1UserMessage":{"type":"object","properties":{"user":{"type":"string","title":"The user who authored the message.\nFormat: users/{user}"},"content":{"type":"string","description":"Simple text content."},"content_list":{"$ref":"#/components/schemas/v1InputContentList"}},"description":"A message from a user."},"v1InputContentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/v1InputContent"},"description":"The list of input content items."}},"description":"A list of input content items (can contain text and/or binary content).","required":["items"]},"v1InputContent":{"type":"object","properties":{"text":{"type":"string","description":"Text content."},"file":{"$ref":"#/components/schemas/v1FileInputContent"}},"description":"InputContent represents a single input item that can be text or binary."},"v1FileInputContent":{"type":"object","properties":{"remote":{"type":"string","title":"Reference to a remote file via URL or file path"},"inline":{"$ref":"#/components/schemas/v1FileContent"}},"description":"FileInputContent represents a file that can be either stored inline or referenced remotely."},"v1FileContent":{"type":"object","properties":{"mime_type":{"type":"string","description":"The MIME type of the file."},"content":{"type":"string","format":"byte","title":"The raw binary content of the file"},"filename":{"type":"string","title":"The name of the file, including extension if applicable"}},"description":"FileContent represents a file with its name and binary content.","required":["mime_type","content"]},"v1AgentMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A message from the AI agent."},"v1ToolCallRequest":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"display_name":{"type":"string","description":"The display name of the tool being called.","readOnly":true},"input":{"type":"string","description":"The input arguments passed to the tool. Contains arbitrary data in a tool-specific format\nthat the agent generates for the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call arguments.","readOnly":true}},"description":"A tool call request made by the AI agent."},"v1ToolCallResult":{"type":"object","properties":{"tool_call_id":{"type":"string","description":"The unique identifier for the tool call. Used to match the tool call request with the tool call result.","readOnly":true},"result":{"type":"string","description":"The result of the tool call.\nNote: Clients should not parse this field. The length of this field may change during\nSTATE_STREAMING as the agent constructs the tool call result.","readOnly":true}},"description":"A tool call result returned by the tool."},"v1Thinking":{"type":"object","properties":{"content":{"type":"string","description":"The thinking content. CommonMark(GFM) formatted.","readOnly":true}},"description":"Thinking or reasoning by the AI agent."},"v1SystemMessage":{"type":"object","properties":{"content":{"type":"string","description":"The content of the system message. CommonMark(GFM) formatted.","readOnly":true}},"description":"A system-generated message."},"v1CompletionResponse":{"type":"object","properties":{"content":{"type":"string","description":"Final content if successful."},"error":{"type":"string","description":"Error description if the request failed."}},"description":"Terminal completion for the agent workflow."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events/{event_id}":{"get":{"summary":"Get Event","operationId":"GetEvent","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1Event"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events:stream > Stream Events ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:stream":{"get":{"summary":"Stream Events","operationId":"StreamEvents","responses":{"200":{"description":"NDJSON stream of StreamEventsResponse objects (one JSON object per line)","content":{"application/x-ndjson":{"schema":{"type":"string","format":"binary","title":"NDJSON stream of StreamEventsResponse objects"}}}},"default":{"description":"An unexpected error response.","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/runs/{run\_id}/agents/{agent\_id}/events:cancelGeneration > Cancel Generation ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CancelGenerationResponse":{"type":"object","description":"Response for canceling ongoing event generation.\nEmpty response. Reserved for future extensibility."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/runs/{run_id}/agents/{agent_id}/events:cancelGeneration":{"post":{"summary":"Cancel Generation","operationId":"CancelGeneration","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CancelGenerationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptionGroups > List Exception Groups ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListExceptionGroupsResponse":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionGroup"},"description":"Available exception groups and their metadata."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."}},"description":"Response containing available exception groups."},"v1ExceptionGroup":{"type":"object","properties":{"name":{"type":"string","description":"The static types (e.g., \"missing_values\", \"user_system_error\", \"internal_error\").\ngroup name is fully qualified\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nThis is maintained by the system until we promote these to full resources.\nThis is the value used in the Exception.group field."},"title":{"type":"string","description":"Human-readable display name for UI."},"description":{"type":"string","description":"Description of what this group represents."},"suggested_action":{"type":"string","description":"Suggested action to resolve exceptions in this group."},"default_assignee":{"type":"string","title":"Default assignee for new exceptions in this group.\nWhen set, new exceptions in this group will be automatically assigned to this user.\nEmpty string means no default assignee is set.\nFormat: users/{user}"}},"description":"Groups are not full resources and cannot be created or modified via the API (for now)\nIn future, we may promote these to full resources."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups":{"get":{"summary":"List Exception Groups","operationId":"ListExceptionGroups","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListExceptionGroupsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of groups to return.\nNote: Since groups are static and typically small in number,\npagination is not strictly necessary but included for AIP compliance.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token from a previous ListExceptionGroups call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptions:countByGroup > Count Exceptions By Group ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountExceptionsByGroupResponse":{"type":"object","properties":{"group_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionGroupCount"},"description":"Exception counts by group, including metadata for each group."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"Total number of groups with exceptions (across all pages).\nRespects the filter from the request."},"total_exception_count":{"type":"integer","format":"int32","description":"Total count of all exceptions across all groups.\nRespects the filter from the request.\nThis is the sum of all counts in group_counts (across all pages).\nUseful for displaying summary statistics like \"110 total exceptions across 3 groups\"."}},"description":"Response containing exception counts by group."},"v1ExceptionGroupCount":{"type":"object","properties":{"group":{"$ref":"#/components/schemas/v1ExceptionGroup"},"count":{"type":"integer","format":"int32","description":"Number of exceptions in this group."}},"description":"Exception count for a specific group, including group metadata."},"v1ExceptionGroup":{"type":"object","properties":{"name":{"type":"string","description":"The static types (e.g., \"missing_values\", \"user_system_error\", \"internal_error\").\ngroup name is fully qualified\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/missing_values\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/user_system_error\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/exceptionGroups/internal_error\nThis is maintained by the system until we promote these to full resources.\nThis is the value used in the Exception.group field."},"title":{"type":"string","description":"Human-readable display name for UI."},"description":{"type":"string","description":"Description of what this group represents."},"suggested_action":{"type":"string","description":"Suggested action to resolve exceptions in this group."},"default_assignee":{"type":"string","title":"Default assignee for new exceptions in this group.\nWhen set, new exceptions in this group will be automatically assigned to this user.\nEmpty string means no default assignee is set.\nFormat: users/{user}"}},"description":"Groups are not full resources and cannot be created or modified via the API (for now)\nIn future, we may promote these to full resources."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByGroup":{"get":{"summary":"Count Exceptions By Group","operationId":"CountExceptionsByGroup","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountExceptionsByGroupResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter to apply before counting (same syntax as ListExceptions).\nUse this to count within a specific state, automation, time range, etc.\nExample: \"state = PENDING\" to count only pending exceptions by group.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of groups to return.\nIf unspecified, at most 50 groups will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token from a previous CountExceptionsByGroup call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/exceptions:countByAutomation > Count Exceptions By Automation ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1CountExceptionsByAutomationResponse":{"type":"object","properties":{"automation_counts":{"type":"array","items":{"$ref":"#/components/schemas/v1ExceptionAutomationCount"},"description":"Exception counts by automation."},"next_page_token":{"type":"string","description":"Token to retrieve the next page of results.\nEmpty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"Total number of automations with exceptions (across all pages).\nRespects the filter from the request."},"total_exception_count":{"type":"integer","format":"int32","description":"Total count of all exceptions across all automations.\nRespects the filter from the request.\nThis is the sum of all counts in automation_counts (across all pages).\nUseful for displaying summary statistics like \"500 total exceptions across 25 automations\"."}},"description":"Response containing exception counts by automation."},"v1ExceptionAutomationCount":{"type":"object","properties":{"automation":{"type":"string","title":"The automation resource name.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}"},"count":{"type":"integer","format":"int32","description":"Number of exceptions for this automation."}},"description":"Exception count for a specific automation."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/exceptions:countByAutomation":{"get":{"summary":"Count Exceptions By Automation","operationId":"CountExceptionsByAutomation","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1CountExceptionsByAutomationResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter","description":"Optional filter to apply before counting (same syntax as ListExceptions).\nUse this to count within a specific state, group, time range, etc.\nExample: \"state = PENDING\" to count only pending exceptions by automation.\nExample: \"group = \\\"missing_values\\\"\" to count exceptions in missing_values group by automation.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of automations to return.\nIf unspecified, at most 50 automations will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token from a previous CountExceptionsByAutomation call.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/guideEntries/{guide\_entry\_id} > Get Guide Entry ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n - resolution_steps: The primary resolution instructions\n - resolution_code: Supporting code examples\n - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}":{"get":{"summary":"Get Guide Entry","operationId":"GetGuideEntry","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1GuideEntry"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"guide_entry_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/automations/{automation\_id}/guideEntries > List Guide Entries ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Exceptions","description":"Track exceptions, view analytics, manage agent events, and access troubleshooting guides."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1ListGuideEntriesResponse":{"type":"object","properties":{"guide_entries":{"type":"array","items":{"$ref":"#/components/schemas/v1GuideEntry"},"title":"The guide entries"},"next_page_token":{"type":"string","description":"A token to retrieve the next page of results.\nPass this value in the `page_token` field in the subsequent call to `ListGuideEntries`\nto continue listing results. Will be empty when there are no more results."},"total_size":{"type":"integer","format":"int32","description":"The total number of guide entries across all pages.\nThis count respects the show_deleted parameter but is not affected by page_size or page_token."}},"title":"Response to a list guide entries request"},"v1GuideEntry":{"type":"object","properties":{"name":{"type":"string","title":"Resource name\nFormat: organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries/{guide_entry_id}"},"content":{"type":"string","description":"Markdown-formatted entry content\nDeprecated: Use resolution_steps and resolution_code instead."},"source_exception":{"type":"string","title":"Exception that led to this entry's creation"},"source_run":{"type":"string","title":"Run where this entry was first created"},"create_time":{"type":"string","format":"date-time","title":"Creation timestamp","readOnly":true},"update_time":{"type":"string","format":"date-time","title":"Last update timestamp","readOnly":true},"delete_time":{"type":"string","format":"date-time","description":"The time when this guide entry was soft-deleted.\nIf not set, the entry has not been deleted.\nSoft-deleted entries are not physically removed but marked as deleted.\nAlways set the state to STATE_ARCHIVED whenever the entry is soft-deleted.","readOnly":true},"title":{"type":"string","description":"Title of the guide entry\nMarked as optional for backwards compatibility.\nCan be set when creating or updating the guide entry."},"automation":{"type":"string","title":"The automation that the guide entry belongs to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"root_cause":{"type":"string","description":"Root cause analysis explaining why the exception occurred.\nThis provides technical context about what caused the issue.\nMarked as optional for backwards compatibility."},"state":{"$ref":"#/components/schemas/v1GuideEntryState"},"version":{"type":"string","title":"Semantic version of this specific version of the guide entry (format: major.minor).\nIncremented each time the guide entry is updated.\nExamples: \"0.1\", \"1.0\", \"1.1\", \"2.0\"","readOnly":true},"resolution_steps":{"type":"string","description":"Human-readable explanation of the resolution action and steps.\nGitHub Flavored Markdown (GFM) formatted.\n\nResolution Field Guidelines:\n- At least one of resolution_steps, resolution_code, or resolution_notes should be present\n for the guide entry to be useful. Entries with none of these fields are considered incomplete.\n- These fields are complementary and can be used together:\n - resolution_steps: The primary resolution instructions\n - resolution_code: Supporting code examples\n - resolution_notes: Additional context or caveats"},"resolution_code":{"type":"string","description":"Example code illustrating how this type of exception was resolved.\nServes as a reference when handling similar exceptions in future runs.\nMay require adaptation based on specific context and should not be applied verbatim."},"resolution_notes":{"type":"string","description":"Additional notes, caveats, or context about the resolution.\nGitHub Flavored Markdown (GFM) formatted.\nUse for edge cases, warnings, or supplementary information."}},"title":"A troubleshooting guide entry for an automation"},"v1GuideEntryState":{"type":"string","enum":["STATE_UNSPECIFIED","STATE_PENDING_APPROVAL","STATE_APPROVED","STATE_REJECTED","STATE_ARCHIVED"],"default":"STATE_UNSPECIFIED","description":"The state of a guide entry.\n\n - STATE_UNSPECIFIED: The state is not specified.\n - STATE_PENDING_APPROVAL: The guide entry is pending approval.\n - STATE_APPROVED: The guide entry is approved.\n - STATE_REJECTED: The guide entry is rejected.\n - STATE_ARCHIVED: The guide entry is archived."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/automations/{automation_id}/guideEntries":{"get":{"summary":"List Guide Entries","operationId":"ListGuideEntries","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1ListGuideEntriesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page_size","description":"The maximum number of guide entries to return. The service may return fewer than this value.\nIf unspecified, at most 50 guide entries will be returned.\nThe maximum value is 1000; values above 1000 will be coerced to 1000.\nNote: These limits are enforced by server-side validation.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"The page token, received from a previous `ListGuideEntries` call.\nProvide this to retrieve the subsequent page.\nWhen paginating, all other parameters provided to `ListGuideEntries` must match\nthe call that provided the page token.","in":"query","required":false,"schema":{"type":"string"}},{"name":"show_deleted","description":"If true, soft-deleted guide entries will be included in the results.\nDeleted entries have delete_time set.\nDefaults to false (deleted entries are filtered out).","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"filter","description":"The filter to apply to the list of guide entries.\nFollows Google AIP-160 filtering standard (https://google.aip.dev/160).\n\nSupported Fields:\n- title: Guide entry title (partial match only)\n- resolution_steps: Resolution steps content (partial match only)\n- resolution_code: Resolution code content (partial match only)\n- resolution_notes: Resolution notes content (partial match only)\n- automation: Automation ID (exact match only)\n- create_time: Guide entry creation timestamp (ISO 8601 format)\n- update_time: Guide entry update timestamp (ISO 8601 format)\n- content: (DEPRECATED) Guide entry content - use resolution_steps, resolution_code, or resolution_notes instead\n\nSupported Operators:\n- Comparison: =, !=, <, <=, >, >=\n- Logical: AND, OR, NOT\n- Grouping: ( )\n- Partial Match: contains\n\nExample Filters:\n- \"title contains 'My Guide Entry'\" - List guide entries with title containing \"My Guide Entry\"\n- \"resolution_steps contains 'restart'\" - List guide entries with resolution steps containing \"restart\"\n- \"resolution_code contains 'retry'\" - List guide entries with resolution code containing \"retry\"\n- \"automation = my-automation-id\" - List guide entries for a specific automation. Use \"-\" as the automation_id to list guide entries across all automations in the workspace.\n- \"automation = my-automation-id or automation = another-automation-id\" - List guide entries for specific automations.\n- \"create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Guide entries created after Jan 1, 2025\n- \"update_time >= \\\"2025-01-01T00:00:00Z\\\" AND update_time < \\\"2025-02-01T00:00:00Z\\\"\" - January 2025 guide entries\n- \"(title contains 'My Guide Entry' OR resolution_steps contains 'error') AND create_time > \\\"2025-01-01T00:00:00Z\\\"\" - Recent guide entries with specific title or resolution steps","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Exceptions"]}}}} ``` # Analytics Query dashboards, automation estimates, insights, and metrics. ## POST /api/v1/organizations/{organization\_id}/workspaces/{workspace\_id}/dashboards:configureAutomationEstimates > Configure Automation Estimates ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Query dashboards, automation estimates, insights, and metrics."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"dashboardsConfigureAutomationEstimatesResponse":{"type":"object","properties":{"automation_estimates":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsAutomationEstimate"},"description":"The list of configured automation estimates.","readOnly":true}},"description":"Response message for ConfigureAutomationEstimates method.\nReturns the configured automation estimates for the workspace."},"dashboardsAutomationEstimate":{"type":"object","properties":{"automation_id":{"type":"string","title":"The automation ID this estimate applies to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}"},"cost_usd":{"type":"string","description":"The estimated cost saved per run in USD."},"time_saved_secs":{"type":"integer","format":"int32","description":"The estimated time saved per run in seconds."}},"description":"AutomationEstimate represents the estimated value metrics for an automation.","required":["automation_id","cost_usd","time_saved_secs"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}},"ConfigureAutomationEstimatesBody":{"type":"object","properties":{"automation_estimates":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsAutomationEstimate"},"description":"The list of automation estimates to configure."}},"description":"Request message for ConfigureAutomationEstimates method.\nConfigures the estimated cost and time savings for automations within a workspace.","required":["automation_estimates"]}}},"paths":{"/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/dashboards:configureAutomationEstimates":{"post":{"summary":"Configure Automation Estimates","operationId":"ConfigureAutomationEstimates","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dashboardsConfigureAutomationEstimatesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureAutomationEstimatesBody"}}},"required":true},"tags":["Analytics"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/dashboards:queryInsights > Query Insights ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Query dashboards, automation estimates, insights, and metrics."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"dashboardsQueryInsightsResponse":{"type":"object","properties":{"value_insight":{"$ref":"#/components/schemas/dashboardsValueInsight"},"run_insight":{"$ref":"#/components/schemas/dashboardsRunInsight"},"completion_insight":{"$ref":"#/components/schemas/dashboardsCompletionInsight"},"awaiting_guidance_insight":{"$ref":"#/components/schemas/dashboardsAwaitingGuidanceInsight"}},"description":"Response message for QueryInsights method.\nContains aggregated analytics insights across value, runs, and completions."},"dashboardsValueInsight":{"type":"object","properties":{"total_money_saved_usd":{"type":"string","description":"Total money saved across all automations and workspaces in USD.","readOnly":true},"total_time_saved_secs":{"type":"string","format":"int64","description":"Total time saved across all automations and workspaces in seconds.","readOnly":true},"insights_per_automation_per_workspace":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/dashboardsAutomationValueInsightList"},"title":"Value insights grouped per automation per workspace.\nKey: workspace_id (format: organizations/{org}/workspaces/{workspace})","readOnly":true},"insights_per_period_per_workspace":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/dashboardsCumulativeValueInsightList"},"title":"Value insights grouped per time period per workspace.\nKey: workspace_id (format: organizations/{org}/workspaces/{workspace})","readOnly":true}},"description":"ValueInsight contains aggregated value metrics (cost and time savings)."},"dashboardsAutomationValueInsightList":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsAutomationValueInsight"},"description":"List of value insights per automation.","readOnly":true}},"description":"AutomationValueInsightList contains value insights for automations within a workspace."},"dashboardsAutomationValueInsight":{"type":"object","properties":{"automation_id":{"type":"string","title":"The automation ID.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"display_name":{"type":"string","description":"The display name of the automation.","readOnly":true},"time_saved_secs":{"type":"string","format":"int64","description":"Time saved by this automation in seconds.","readOnly":true},"money_saved_usd":{"type":"string","description":"Money saved by this automation in USD.","readOnly":true}},"description":"AutomationValueInsight contains value metrics for a specific automation."},"dashboardsCumulativeValueInsightList":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsCumulativeValueInsight"},"description":"List of value insights per time period.","readOnly":true}},"description":"CumulativeValueInsightList contains value insights grouped per time period within a workspace."},"dashboardsCumulativeValueInsight":{"type":"object","properties":{"window_label":{"type":"string","description":"The display label of the time period (e.g., \"Week 1\", \"January 2025\").","readOnly":true},"time_saved_secs":{"type":"string","format":"int64","description":"Time saved during this period in seconds.","readOnly":true},"money_saved_usd":{"type":"string","description":"Money saved during this period in USD.","readOnly":true}},"description":"CumulativeValueInsight contains value metrics for a specific time period."},"dashboardsRunInsight":{"type":"object","properties":{"total_runs_count":{"type":"string","format":"int64","description":"Total number of runs across all automations and workspaces.","readOnly":true},"insights_per_automation_per_workspace":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/dashboardsAutomationRunInsightList"},"title":"Run insights grouped per automation per workspace.\nKey: workspace_id (format: organizations/{org}/workspaces/{workspace})","readOnly":true},"insights_per_period_per_workspace":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/dashboardsCumulativeRunInsightList"},"title":"Run insights grouped per time period per workspace.\nKey: workspace_id (format: organizations/{org}/workspaces/{workspace})","readOnly":true},"trend":{"$ref":"#/components/schemas/dashboardsTrend"}},"description":"RunInsight contains aggregated runCount metrics."},"dashboardsAutomationRunInsightList":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsAutomationRunInsight"},"description":"List of run insights per automation.","readOnly":true}},"description":"AutomationRunInsightList contains run insights for automations within a workspace."},"dashboardsAutomationRunInsight":{"type":"object","properties":{"automation_id":{"type":"string","title":"The automation ID.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}","readOnly":true},"display_name":{"type":"string","description":"The display name of the automation.","readOnly":true},"runs_count":{"type":"string","format":"int64","description":"Number of runs for this automation.","readOnly":true}},"description":"AutomationRunInsight contains run count metrics for a specific automation."},"dashboardsCumulativeRunInsightList":{"type":"object","properties":{"values":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsCumulativeRunInsight"},"description":"List of run insights per time period.","readOnly":true}},"description":"CumulativeRunInsightList contains run insights grouped per time period within a workspace."},"dashboardsCumulativeRunInsight":{"type":"object","properties":{"window_label":{"type":"string","description":"The display label of the time period (e.g., \"Week 1\", \"January 2025\").","readOnly":true},"runs_count":{"type":"string","format":"int64","description":"Number of runs during this period.","readOnly":true}},"description":"CumulativeRunInsight contains run count metrics for a specific time period."},"dashboardsTrend":{"type":"object","properties":{"percent_change":{"type":"number","format":"double","description":"The percentage change compared to the previous time window.\nPositive values indicate increase, negative values indicate decrease.","readOnly":true},"comparison_window":{"type":"string","description":"The label of the time window being compared against (e.g., \"Last Week\", \"Previous Month\").","readOnly":true}},"description":"Trend represents a percentage change compared to a previous time window."},"dashboardsCompletionInsight":{"type":"object","properties":{"total_percent_completions":{"type":"number","format":"double","description":"Overall completion percentage across all runs.","readOnly":true},"completions_per_period":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsCumulativeCompletionInsight"},"description":"Completion insights grouped per time period.","readOnly":true},"trend":{"$ref":"#/components/schemas/dashboardsTrend"},"stp":{"type":"number","format":"double","description":"Straight-through processing rate.","readOnly":true}},"description":"CompletionInsight contains completion rate metrics."},"dashboardsCumulativeCompletionInsight":{"type":"object","properties":{"window_label":{"type":"string","description":"The display label of the time period (e.g., \"Week 1\", \"January 2025\").","readOnly":true},"auto_completed_count":{"type":"string","format":"int64","description":"Number of runs that completed automatically without manual intervention.","readOnly":true},"manually_resolved_count":{"type":"string","format":"int64","description":"Number of runs that required manual resolution.","readOnly":true}},"description":"CumulativeCompletionInsight contains completion metrics for a specific time period."},"dashboardsAwaitingGuidanceInsight":{"type":"object","properties":{"total_runs_awaiting_guidance":{"type":"string","format":"int64","description":"Total number of runs awaiting guidance.","readOnly":true},"runs_per_period":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsRunsAwaitingGuidanceByPeriod"},"description":"Runs awaiting guidance grouped per time period.","readOnly":true}},"description":"AwaitingGuidanceInsight contains metrics for runs awaiting guidance."},"dashboardsRunsAwaitingGuidanceByPeriod":{"type":"object","properties":{"window_label":{"type":"string","description":"The display label of the time period (e.g., \"January 2026\", \"December 2025\").","readOnly":true},"runs_awaiting_guidance":{"type":"string","format":"int64","description":"Number of runs created in this period that are awaiting guidance.","readOnly":true}},"description":"RunsAwaitingGuidanceByPeriod contains runs awaiting guidance for a specific time period."},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/dashboards:queryInsights":{"get":{"summary":"Query Insights","operationId":"QueryInsights","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dashboardsQueryInsightsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"filter.workspace_ids","description":"Optional list of workspace IDs to filter insights.\nFormat: organizations/{organization}/workspaces/{workspace}\nIf empty, insights for all workspaces are returned.","in":"query","required":false,"explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"filter.automation_ids","description":"Optional list of automation IDs to filter insights.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}\nIf empty, insights for all automations are returned.","in":"query","required":false,"explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"filter.time_window.start_time","description":"The start time of the window (inclusive).","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"filter.time_window.end_time","description":"The end time of the window (inclusive).","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"filter.time_window.time_zone","description":"The timezone for interpreting the time window.\nFormat: IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\").\nDefaults to \"UTC\" if not specified.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Analytics"]}}}} ``` ## GET /api/v1/organizations/{organization\_id}/dashboards:queryAutomationEstimates > Query Automation Estimates ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Query dashboards, automation estimates, insights, and metrics."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"dashboardsQueryAutomationEstimatesResponse":{"type":"object","properties":{"workspace_estimates":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/dashboardsAutomationEstimateList"},"title":"Automation estimates grouped per workspace.\nKey: workspace_id (format: organizations/{org}/workspaces/{workspace})","readOnly":true}},"description":"Response message for QueryAutomationEstimates method.\nContains automation estimates grouped by workspace."},"dashboardsAutomationEstimateList":{"type":"object","properties":{"estimates":{"type":"array","items":{"$ref":"#/components/schemas/dashboardsAutomationEstimate"},"description":"List of automation estimates for a workspace.","readOnly":true}},"description":"Wrapper for a list of automation estimates."},"dashboardsAutomationEstimate":{"type":"object","properties":{"automation_id":{"type":"string","title":"The automation ID this estimate applies to.\nFormat: organizations/{organization}/workspaces/{workspace}/automations/{automation}"},"cost_usd":{"type":"string","description":"The estimated cost saved per run in USD."},"time_saved_secs":{"type":"integer","format":"int32","description":"The estimated time saved per run in seconds."}},"description":"AutomationEstimate represents the estimated value metrics for an automation.","required":["automation_id","cost_usd","time_saved_secs"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/dashboards:queryAutomationEstimates":{"get":{"summary":"Query Automation Estimates","operationId":"QueryAutomationEstimates","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dashboardsQueryAutomationEstimatesResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}}],"tags":["Analytics"]}}}} ``` ## Query Metrics > This RPC retrieves time-series metric data for a specific organization,\ > supporting multiple metrics in a single request. Results can be filtered,\ > grouped, and sorted by tag dimensions.\ > \ > The response contains one result per requested metric. Each result includes\ > multiple time series (one per unique group\_by combination), with each series\ > containing chronologically ordered data points showing the aggregated metric\ > value over time.\ > \ > Use the filter parameter (AIP-160 syntax) to restrict data to specific\ > tag values, and group\_by to break down results by tag dimensions. The\ > order\_by and page\_size parameters enable sorting and limiting results\ > (useful for "top N" queries). The interval and aggregation parameters\ > control how data is aggregated. If not specified, the server will determine\ > appropriate defaults based on the time range.\ > \ > Example use cases:\ > \- Dashboard view: metrics=\["runs", "pages"], group\_by=\["status"]\ > \- Top 10 workspaces: metrics=\["runs"], group\_by=\["workspace\_id"],\ > order\_by="value desc", page\_size=10\ > \- Success rate: metrics=\["runs"], filter='status = "success"'\ > \- Multi-metric comparison: metrics=\["files", "automations"],\ > group\_by=\["workspace\_id"] ```json {"openapi":"3.0.0","info":{"title":"Kognitos API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Query dashboards, automation estimates, insights, and metrics."}],"servers":[{"url":"https://app.us-1.kognitos.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Personal Access Token."}},"schemas":{"v1QueryMetricsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/v1MetricResult"},"description":"Results for each requested metric.\n\nOrdered in the same sequence as the metrics field in the request.\nEach result contains the time series data for one metric.","readOnly":true},"next_page_token":{"type":"string","description":"Token for retrieving the next page of results.\n\nIf non-empty, there are more results available. Pass this value as\npage_token in the next request to retrieve the next page.\n\nIf empty, there are no more results (this is the last page).\n\nWhen paginating, all metrics will include their next page of series.\n\nSee https://google.aip.dev/158 for pagination specification.","readOnly":true}},"description":"Response message for the QueryMetrics RPC.\n\nContains results for each requested metric, with time series data\nand metadata about the query execution.","required":["results"]},"v1MetricResult":{"type":"object","properties":{"metric":{"type":"string","description":"The name of this metric.\n\nEchoes back the metric name from the request.","readOnly":true},"interval":{"$ref":"#/components/schemas/v1MetricInterval"},"aggregation":{"$ref":"#/components/schemas/v1AggregationFunction"},"series":{"type":"array","items":{"$ref":"#/components/schemas/v1MetricSeries"},"description":"Multiple time series, one per unique group_by combination.\n\nIf group_by is empty, there will be exactly one series with empty tags.\nIf group_by has values, there will be one series per unique combination\nfound in the data.\n\nSeries are ordered according to the order_by parameter in the request.\nIf page_size was specified, results are paginated across all metrics.\n\nThe list may be empty if no data exists for the requested time range.","readOnly":true}},"description":"Result for a single metric query.\n\nContains the time series data and metadata for one metric.","required":["metric","interval","aggregation","series"]},"v1MetricInterval":{"type":"string","enum":["METRIC_INTERVAL_UNSPECIFIED","METRIC_INTERVAL_HOUR","METRIC_INTERVAL_DAY","METRIC_INTERVAL_WEEK","METRIC_INTERVAL_MONTH"],"default":"METRIC_INTERVAL_UNSPECIFIED","description":"Time interval for metric aggregation.\n\nSpecifies the granularity at which metric data points are aggregated.\nThe server may adjust the requested interval based on the time range\nor data availability.\n\n - METRIC_INTERVAL_UNSPECIFIED: Unspecified interval. Server will determine appropriate interval.\n - METRIC_INTERVAL_HOUR: Hourly aggregation.\n - METRIC_INTERVAL_DAY: Daily aggregation.\n - METRIC_INTERVAL_WEEK: Weekly aggregation.\n - METRIC_INTERVAL_MONTH: Monthly aggregation."},"v1AggregationFunction":{"type":"string","enum":["AGGREGATION_FUNCTION_UNSPECIFIED","AGGREGATION_FUNCTION_COUNT","AGGREGATION_FUNCTION_SUM","AGGREGATION_FUNCTION_AVG","AGGREGATION_FUNCTION_MIN","AGGREGATION_FUNCTION_MAX"],"default":"AGGREGATION_FUNCTION_UNSPECIFIED","description":"Aggregation function for metric values.\n\nSpecifies how metric values should be aggregated within each interval.\n\n - AGGREGATION_FUNCTION_UNSPECIFIED: Unspecified aggregation. Defaults to COUNT.\n - AGGREGATION_FUNCTION_COUNT: Count of occurrences.\n - AGGREGATION_FUNCTION_SUM: Sum of values.\n - AGGREGATION_FUNCTION_AVG: Average of values.\n - AGGREGATION_FUNCTION_MIN: Minimum value.\n - AGGREGATION_FUNCTION_MAX: Maximum value."},"v1MetricSeries":{"type":"object","properties":{"tags":{"type":"object","additionalProperties":{"type":"string"},"description":"Tags identifying this series.\n\nThe unique combination of group_by tag values that define this series.\nIf group_by is empty, this will be an empty map.\n\nExample: {\"status\": \"success\", \"workspace_id\": \"ws_123\"}","readOnly":true},"points":{"type":"array","items":{"$ref":"#/components/schemas/v1MetricDataPoint"},"description":"Time series data points for this specific tag combination.\n\nChronologically ordered data points showing the metric value over time.","readOnly":true}},"description":"A single time series for a specific combination of tag values.\n\nEach series represents one unique combination of the group_by dimensions,\ncontaining data points over time for that specific combination.","required":["tags","points"]},"v1MetricDataPoint":{"type":"object","properties":{"start_time":{"type":"string","format":"date-time","description":"The start time for this data point's interval.\n\nRepresents the start of the interval for which the value is aggregated.","readOnly":true},"value":{"type":"number","format":"double","description":"The aggregated metric value for this interval.\n\nResult of applying the aggregation function to all matching records\nwithin this interval for this series' tag combination.","readOnly":true},"window_label":{"type":"string","description":"Human-readable label for the time window.\n\nProvides a formatted display name for the interval, formatted according\nto the interval granularity and the user's locale preferences.\n\nExamples:\n- HOUR: \"Jan 15, 2025 10:00 AM\", \"2025-01-15 10:00\"\n- DAY: \"January 15, 2025\", \"2025-01-15\"\n- WEEK: \"Week of Jan 15, 2025\", \"2025-W03\"\n- MONTH: \"January 2025\", \"2025-01\"","readOnly":true}},"description":"A single data point in a metric time series.\n\nRepresents an aggregated metric value at a specific point in time.","required":["start_time","value","window_label"]},"rpcStatus":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"details":{"type":"array","items":{"$ref":"#/components/schemas/protobufAny"}}}},"protobufAny":{"type":"object","properties":{"@type":{"type":"string"}},"additionalProperties":{}}}},"paths":{"/api/v1/organizations/{organization_id}/metrics:query":{"get":{"summary":"Query Metrics","description":"This RPC retrieves time-series metric data for a specific organization,\nsupporting multiple metrics in a single request. Results can be filtered,\ngrouped, and sorted by tag dimensions.\n\nThe response contains one result per requested metric. Each result includes\nmultiple time series (one per unique group_by combination), with each series\ncontaining chronologically ordered data points showing the aggregated metric\nvalue over time.\n\nUse the filter parameter (AIP-160 syntax) to restrict data to specific\ntag values, and group_by to break down results by tag dimensions. The\norder_by and page_size parameters enable sorting and limiting results\n(useful for \"top N\" queries). The interval and aggregation parameters\ncontrol how data is aggregated. If not specified, the server will determine\nappropriate defaults based on the time range.\n\nExample use cases:\n- Dashboard view: metrics=[\"runs\", \"pages\"], group_by=[\"status\"]\n- Top 10 workspaces: metrics=[\"runs\"], group_by=[\"workspace_id\"],\n order_by=\"value desc\", page_size=10\n- Success rate: metrics=[\"runs\"], filter='status = \"success\"'\n- Multi-metric comparison: metrics=[\"files\", \"automations\"],\n group_by=[\"workspace_id\"]","operationId":"QueryMetrics","responses":{"200":{"description":"A successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/v1QueryMetricsResponse"}}}},"default":{"description":"An unexpected error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/rpcStatus"}}}}},"parameters":[{"name":"organization_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"metrics","description":"The names of the metrics to query.\n\nIdentifies which metric types to retrieve data for in a single request.\nAll metrics will use the same filter, group_by, time range, interval,\nand aggregation settings.\n\nExamples: [\"runs\"], [\"runs\", \"pages\"], [\"files\", \"automations\"]","in":"query","required":true,"explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"filter","description":"Filter expression to apply before aggregation.\n\nReduces the dataset to only records matching the filter criteria.\nUses the AIP-160 filtering syntax for flexible query expressions.\nAn empty string means no filtering (all records included).\n\nSupported operators: =, !=, AND, OR, NOT, IN\n\nExamples:\n- 'status = \"success\"'\n- 'status = \"success\" AND workspace_id = \"ws_123\"'\n- 'status IN [\"success\", \"pending\"]'\n- 'workspace_id = \"ws_123\" OR workspace_id = \"ws_456\"'\n\nSee https://google.aip.dev/160 for full syntax specification.","in":"query","required":false,"schema":{"type":"string"}},{"name":"group_by","description":"Tag dimensions to group results by.\n\nEach unique combination of these tag values becomes a separate time series.\nAn empty list means no grouping (single aggregated series).\n\nExamples: [\"status\"], [\"workspace_id\", \"status\"]","in":"query","required":false,"explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"start_time","description":"Start time for the query range (inclusive).\n\nData points with timestamps on or after this time will be included.","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"end_time","description":"End time for the query range (exclusive).\n\nData points with timestamps before this time will be included.","in":"query","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"interval","description":"Requested time interval for aggregation.\n\nSpecifies the desired granularity for data points. The server may\nadjust this based on the time range or data availability.\n\nIf unspecified, the server will determine an appropriate interval.\n\n - METRIC_INTERVAL_UNSPECIFIED: Unspecified interval. Server will determine appropriate interval.\n - METRIC_INTERVAL_HOUR: Hourly aggregation.\n - METRIC_INTERVAL_DAY: Daily aggregation.\n - METRIC_INTERVAL_WEEK: Weekly aggregation.\n - METRIC_INTERVAL_MONTH: Monthly aggregation.","in":"query","required":false,"schema":{"type":"string","enum":["METRIC_INTERVAL_UNSPECIFIED","METRIC_INTERVAL_HOUR","METRIC_INTERVAL_DAY","METRIC_INTERVAL_WEEK","METRIC_INTERVAL_MONTH"],"default":"METRIC_INTERVAL_UNSPECIFIED"}},{"name":"aggregation","description":"Aggregation function to apply to metric values.\n\nSpecifies how values should be combined within each interval.\n\nIf unspecified, defaults to COUNT.\n\n - AGGREGATION_FUNCTION_UNSPECIFIED: Unspecified aggregation. Defaults to COUNT.\n - AGGREGATION_FUNCTION_COUNT: Count of occurrences.\n - AGGREGATION_FUNCTION_SUM: Sum of values.\n - AGGREGATION_FUNCTION_AVG: Average of values.\n - AGGREGATION_FUNCTION_MIN: Minimum value.\n - AGGREGATION_FUNCTION_MAX: Maximum value.","in":"query","required":false,"schema":{"type":"string","enum":["AGGREGATION_FUNCTION_UNSPECIFIED","AGGREGATION_FUNCTION_COUNT","AGGREGATION_FUNCTION_SUM","AGGREGATION_FUNCTION_AVG","AGGREGATION_FUNCTION_MIN","AGGREGATION_FUNCTION_MAX"],"default":"AGGREGATION_FUNCTION_UNSPECIFIED"}},{"name":"order_by","description":"Ordering for series results within each metric.\n\nUses AIP-132 syntax: \"field_name [asc|desc]\"\nMultiple orderings can be comma-separated.\n\nSupported fields:\n- Tag names from group_by (e.g., \"workspace_id asc\", \"status desc\")\n- \"value\" for sorting by aggregated metric value (uses last data point)\n\nExamples:\n- \"value desc\" - Highest values first (e.g., top workspaces)\n- \"workspace_id asc\" - Alphabetical by workspace ID\n- \"value desc, workspace_id asc\" - By value descending, then workspace ascending\n\nIf unspecified, series are returned in arbitrary order.\n\nSee https://google.aip.dev/132 for full syntax specification.","in":"query","required":false,"schema":{"type":"string"}},{"name":"page_size","description":"Maximum number of series to return per metric.\n\nLimits the number of time series in each metric's results.\nUseful with order_by for \"top N\" queries.\n\nIf unspecified or zero, all matching series are returned.\nIf page_size is larger than the number of matching series, all series\nare returned.\n\nExample: order_by=\"value desc\", page_size=10 returns top 10 series.","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"page_token","description":"Pagination token for retrieving the next page of series.\n\nWhen a response contains more series than page_size, the next_page_token\nfrom the response can be passed here to retrieve the next page.\n\nIf empty, returns the first page of results.\n\nSee https://google.aip.dev/158 for pagination specification.","in":"query","required":false,"schema":{"type":"string"}}],"tags":["Analytics"]}}}} ``` # User Options Manage your profile, preferences, and account access in Kognitos. ## Overview User options control your personal experience in Kognitos. These preferences let you customize how the platform looks and works for you. Use them to update your profile information, choose your preferred visual theme, connect to remote services, and manage other settings.
## Menu Options Click on your name or your profile avatar in the bottom-left corner to open the user menu. The following options are available: ### 1. Documentation Access the [**Kognitos Documentation**](https://docs.kognitos.com) and support resources. ### 2. Workspace Settings Access settings for your current workspace, including user management and workspace configuration. See [**Workspace Settings**](/guides/administration/user-options/workspace-settings) for more details. ### 3. Organization Settings Manage organization-wide settings, workspaces, and users. See [**Organization Settings**](/guides/administration/user-options/organization-settings) for more details. ### 4. Remote Connections Set up a secure IPsec VPN tunnel to reach on-premises or private network services from your automations. See [**Remote Connections**](/guides/administration/user-options/remote-connections) for more details. ### 5. Appearance Customize how Kognitos looks on your device. Choose between light and dark themes, or set it to follow your system preferences. Dark mode is the default theme. ### 6. Profile Manage your personal account information, including your name and email. ### 7. Logging Out When you're done working, select **Log out** to securely end your session. You'll need to [log in](/guides/getting-started/quick-start#log-in) again to access your account. ### 8. Switching Organization If you belong to multiple organizations, use the **Switch organization** option to move between them. Each organization has its own workspaces, automations, and settings. # Workspace Settings Manage users, roles, and permissions for your workspace. ## Overview Workspace settings control your automation environment. Each workspace operates independently with its own users, permissions, and automations. Use these settings to manage who can access your workspace and what they can do. ## Settings To access your workspace settings, click on your name or profile avatar in the bottom-left corner to open the user menu. Then select **Workspace settings**.
### Overview View essential information about your workspace in the **Overview**: * **Workspace name** - The identifier for this environment *(editable).* * **Owner** - Who manages the workspace. * **Created** - When the workspace was established.
### Users Manage who has access to your workspace and what they can do. The **Users** section includes three tabs: [**Roles**](#roles), [**Workspace Users**](#workspace-users), and [**Pending Invites**](#pending-invites).
#### Roles View all the workspace roles and permission levels: * **Automation Author** - Create and manage automations * **Automation Operator** - Run and monitor automations * **CXO** - Read-only executive access to workspace activity * **IT/Integrator** - Manage API keys and external connections * **Member** - Basic workspace access * **Workspace Admin** - Full workspace administration #### Workspace Users View everyone who currently has access to this workspace, along with their assigned roles. #### Pending Invites Track invitations you've sent that haven't been accepted yet. You can access invite links and revoke invites from this tab. ## Inviting Users To add a **team member** to your workspace: {% stepper %} {% step %} **Navigate to Users** Navigate to the **Users** tab within Workspace Settings. {% endstep %} {% step %} **Invite User** Click **+ Invite users** in the top right. {% endstep %} {% step %} **Select a Role** Select a role from the dropdown. This role determines what the user can do within your workspace: * **Automation Author** - Create and manage automations * **Automation Operator** - Run and monitor automations * **CXO** - Read-only executive access to workspace activity * **IT/Integrator** - Manage API keys and external connections * **Member** - Basic workspace access * **Workspace Admin** - Full workspace administration {% endstep %} {% step %} **Enter Email** Enter the user's email address, then click **Invite User**. {% endstep %} {% step %} **Share Invitation Link** Copy the invitation link and share it with your teammate to complete the invitation. {% endstep %} {% endstepper %}
--- [Next Page](/llms-full.txt/1)