# Developer Platform
Welcome to your team’s developer platform
Find the right documentation for your needs
Execute revenue operations with Kaana’s RevOps platform
Ask Kaana AI Contact Support
Need Assistance?
Get support from the Kaana team and access trouble shooting resources.
| | | |
|---|
| Email Support | Contact our support team for assistance, questions, and issues | Email Support | |
| Troubleshooting | Find solutions to common problems and learn about known issues | Troubleshooting | |
# Welcome to Kaana
### What is Kaana?
Kaana is a RevOps execution platform that helps organizations design, run, and continuously improve their revenue operations. It provides a single operating layer across strategy, execution, systems, and insight so revenue teams can stay aligned as they scale.
Kaana supports the full RevOps spectrum, spanning Sales, Marketing, Finance, Product, and Operations.
### Kaana’s role in RevOps
Revenue operations are not a single project or system. They are an evolving set of processes, decisions, and dependencies that span teams and technologies.
Kaana brings this work together by connecting revenue initiatives, system knowledge, collaboration, requirements, risk, and operational insight in one place. This allows organizations to manage RevOps as a system rather than a collection of disconnected efforts.
### What Kaana supports
**Revenue initiatives and workstreams**
Kaana helps teams organize strategic initiatives, operational work, and continuous improvement efforts without forcing everything into a rigid project model. Teams can track ownership, progress, and outcomes while remaining flexible as priorities change.
**Systems and process intelligence**
Kaana provides a centralized place to document how revenue systems and processes work across tools like CRM, billing, and ERP. This creates shared understanding and reduces risk as systems and revenue models evolve.
**Collaboration and activity tracking**
RevOps work happens in meetings, emails, conversations, and decisions. Kaana captures these activities in context so teams can maintain visibility, preserve decision history, and reduce knowledge loss over time.
**Requirements and change management**
Kaana enables teams to define business requirements, assess fit and gaps, and manage change as systems and processes evolve. This helps ensure alignment between business needs and execution before changes impact revenue.
**Issues, risks, and dependencies**
Kaana provides structured visibility into operational issues, blockers, and cross-team dependencies. This allows teams to identify and address risk early rather than reacting after revenue is affected.
**Operational health and insights**
Kaana continuously monitors RevOps health using automated assessments and AI-powered insights. Teams can identify execution risk, inefficiencies, system misalignment, and improvement opportunities across revenue operations.
### Who Kaana is for
**RevOps and operations leaders**
Kaana helps leaders align teams around revenue outcomes, maintain visibility across systems and initiatives, and surface risk early.
**Practitioners and cross-functional teams**
Kaana provides a shared workspace where teams across Sales, Finance, Product, and Operations can collaborate, access documentation, and stay aligned as work evolves.
**Executives**
Kaana gives executives a holistic view of revenue operations health, execution status, and organizational risk, supported by dashboards and reporting.
### Why Kaana exists
Most organizations manage revenue operations across disconnected tools, documents, and conversations. This fragmentation creates risk, slows execution, and makes scaling difficult.
Kaana provides a single RevOps operating layer that connects strategy, execution, systems, and insight so organizations can scale revenue with clarity and confidence.
### Getting started
Log in through your organization’s Kaana login page and explore the dashboard to review revenue initiatives, operational health, and recent activity. Review your assigned work and system context, update your profile, and familiarize yourself with the core areas of the platform.
| Collection | | Link |
|---|
| Managing Projects | Plan and track revenue initiatives and operational workstreams across teams. | Managing Projects |
| Contacts & Organizations | Manage people and companies involved in your revenue operations. | Contacts & Organizations |
| Planning & Resources | Align priorities, timelines, and capacity to support revenue execution. | Planning & Resources |
| System Feed | See real-time activity across initiatives, systems, and teams. | System Feed |
| Managed Services | Understand how Kaana delivers ongoing RevOps execution and support. | Managed Services |
| Billing & Plans | View plan details, billing information, and subscription usage. | Billing & Plans |
# Logging In to Kaana
## Logging In to Kaana
### First-Time Login
{% stepper %}
{% step %}
### Verify email and set password
When your account is created, you'll receive an email with a link to:
* Verify your email address
* Set your password
Click the link in the email and follow the prompts to create a secure password.
{% endstep %}
{% endstepper %}
### Signing In
{% stepper %}
{% step %}
Go to your organization's Kaana login page.
{% endstep %}
{% step %}
Click **Sign In**.
{% endstep %}
{% step %}
Enter your email address and password.
{% endstep %}
{% step %}
Click **Continue**.
{% endstep %}
{% endstepper %}
### Password Requirements
* At least 8 characters long
* Include a mix of letters, numbers, and symbols
* Different from your previous passwords
### Forgot Your Password?
{% stepper %}
{% step %}
On the login page, click **Forgot Password**.
{% endstep %}
{% step %}
Enter your email address.
{% endstep %}
{% step %}
Check your email for a password reset link.
{% endstep %}
{% step %}
Click the link and create a new password.
Note: The reset link expires after 24 hours. If it expires, request a new one.
{% endstep %}
{% endstepper %}
### Trouble Logging In?
#### Common Issues
"Invalid email or password"
* Double-check your email address for typos
* Make sure Caps Lock is off
* Try resetting your password
"Account locked"
* Your account may be locked after multiple failed attempts
* Wait 15 minutes and try again, or contact your administrator
No reset email received
* Check your spam/junk folder
* Make sure you're using the correct email address
* Ask your administrator to verify your account
### Still Need Help?
Contact your organization's administrator or Kaana support for assistance.
### Staying Signed In
For security, you'll be automatically signed out after a period of inactivity. To stay signed in longer on trusted devices, check your browser's "remember me" or related settings.
### Multiple Organizations
If you belong to multiple organizations, you'll select which one to access after signing in. You can switch organizations from your profile menu.
# Navigating the Dashboard
The dashboard is your home base in Kaana. It provides an overview of your projects, tasks, and key metrics at a glance.
## Dashboard Layout
### Navigation Sidebar
On the left side, you'll find the main navigation menu:
* **Dashboard** - Return to this overview page
* **Projects** - View and manage all projects
* **Documents** - Access your document library
* **Activities** - Track meetings, emails, and notes
* **Issues** - View and manage issues
* **Reports** - Access analytics and exports
* **Planning** - Program planner, blueprints, and playbooks
* **Organizations** - Manage client organizations
* **Contacts** - Your contact directory
* **Settings** - Account and system settings
### Main Content Area
The center of the dashboard displays:
* **Key Metrics** - Important numbers like active projects, open tasks, and pending issues
* **Recent Activity** - Latest updates across your projects
* **Quick Actions** - Shortcuts to common tasks
* **Upcoming Deadlines** - Tasks and milestones due soon
## Personalizing Your View
### Rearranging Navigation
{% stepper %}
{% step %}
Go to **Settings** > **Preferences**
{% endstep %}
{% step %}
Drag and drop menu items to reorder
{% endstep %}
{% step %}
Your preferences are saved automatically
{% endstep %}
{% endstepper %}
### Dashboard Widgets
Some dashboard sections can be customized:
* Collapse sections you don't need
* Expand sections to see more details
* Some sections may be filtered based on your role
### Quick Actions
From the dashboard, you can quickly:
* **Create a new project** - Click the "+" button or "New Project"
* **Add a task** - Start typing in the quick task input
* **Upload a document** - Drag and drop files
* **Log an activity** - Record meetings or notes
## Searching
Use the search bar at the top to find:
* Projects by name
* Contacts by name or email
* Documents by title
* Tasks by description
Search results are organized by category for easy navigation.
## Notifications
The notification icon shows alerts for:
* Tasks assigned to you
* Mentions in comments
* Project updates
* Upcoming deadlines
Click the bell icon to view your notification history.
## Getting Help
* Look for the **?** icon for context-sensitive help
* Access the Help Center from the user menu
* Contact support through the Settings page
# Understanding Your Role
Kaana uses role-based access control (RBAC) to determine what you can see and do within the platform.
## Standard Roles
### Owner
The highest level of access within an organization.
* Full access to all features and data
* Can manage billing and subscription
* Can add and remove administrators
* Can configure organization settings
### Admin
Administrative access for managing the organization.
* Create, edit, and delete projects
* Manage users and assign roles
* Configure integrations and settings
* Access all reports and analytics
* Cannot modify billing (unless also Owner)
### Member
Standard access for team members.
* View projects they're assigned to
* Create and update tasks
* Upload and view documents
* Log activities and comments
* Limited access to sensitive settings
### Guest
Read-only access for external collaborators.
* View projects they're invited to
* View documents and activities
* Cannot create or modify content
* Limited navigation access
## What Can You Do?
Your role determines access across different areas:
| Feature | Owner | Admin | Member | Guest |
| ---------------- | ----: | ----: | -----: | ----: |
| View Dashboard | Yes | Yes | Yes | Yes |
| Create Projects | Yes | Yes | Some | No |
| Edit Projects | Yes | Yes | Own | No |
| Delete Projects | Yes | Yes | No | No |
| Upload Documents | Yes | Yes | Yes | No |
| Log Activities | Yes | Yes | Yes | No |
| Create Issues | Yes | Yes | Yes | No |
| Manage Users | Yes | Yes | No | No |
| View Reports | Yes | Yes | Some | No |
| Change Settings | Yes | Yes | No | No |
| Manage Billing | Yes | No | No | No |
## Ownership-Based Access
Some features use ownership-based permissions:
* "Own" items — Content you created or are assigned to
* "All" items — Any content in your organization
For example, a Member might be able to edit their own tasks but not tasks created by others.
## Checking Your Permissions
{% stepper %}
{% step %}
### Open Settings
Go to Settings > Profile.
{% endstep %}
{% step %}
### View Your Role
Your role is displayed on your profile page.
{% endstep %}
{% step %}
### Check Navigation
Navigation shows only features you can access.\
If you need additional access, contact your administrator.
{% endstep %}
{% endstepper %}
## Why Can't I See Something?
If a feature or menu item is missing:
* Your role may not have access to that feature
* The feature may be disabled for your organization
* You may need to be added to specific projects
Contact your administrator if you believe you should have access to something.
## Custom Roles
Your organization may have custom roles with specific permission combinations. Check with your administrator to understand any custom roles in use.
# Search Tips
Learn how to effectively search and find what you need in Kaana.
## Using the Search Bar
The search bar at the top of the page searches across:
* Projects
* Tasks
* Contacts
* Documents
* Organizations
* Issues
{% stepper %}
{% step %}
### Basic Search
* Click the search bar (or press `/`)
* Type your search term
* Press Enter or click Search
* Results appear organized by type
{% endstep %}
{% step %}
### No Results Found?
* Check spelling
* Try different terms
* Use partial words
* Clear filters
* Check the correct section
* Verify you have access
{% endstep %}
{% endstepper %}
## Quick Results
As you type, quick results appear:
* Click a result to go directly to it
* See top matches from each category
* Press Enter for full search
## Search Techniques
### Exact Phrases
Use quotes for exact matches:
```
"project kickoff"
```
Finds items with exactly "project kickoff"
### Partial Matches
Search finds partial matches:
```
mark
```
Finds "Marketing", "Benchmark", "Mark Smith"
### Multiple Terms
Space-separated terms find items with all terms:
```
budget 2024
```
Finds items containing both "budget" and "2024"
## Filtering Results
### By Type
After searching, filter by type:
* Projects only
* Contacts only
* Documents only
* etc.
### By Date
Filter by when created or updated:
* Last 7 days
* Last 30 days
* Custom date range
### By Status
For projects and tasks:
* Active only
* Completed only
* All statuses
## Category-Specific Search
### Projects Search
Find projects by:
* Project name
* Description
* Owner name
* Tags
### Contacts Search
Find contacts by:
* Name
* Email address
* Company
* Phone number
### Documents Search
Find documents by:
* File name
* Description
* Tags
* Uploader
### Tasks Search
Find tasks by:
* Task title
* Description
* Assignee name
* Project name
## Recent Searches
Your recent searches are saved:
* Click the search bar
* See recent searches
* Click to search again
## Search History
View your complete search history:
* Access from your profile
* See what you've searched
* Quick access to past searches
## Keyboard Shortcuts
| Shortcut | Action |
| --------- | ---------------- |
| `/` | Focus search bar |
| `Enter` | Execute search |
| `Esc` | Close search |
| `↑` / `↓` | Navigate results |
## Tips for Better Results
### Be Specific
More specific = better results:
* "Q4 budget review" instead of "budget"
* "John Smith Acme" instead of "John"
### Use Key Terms
Focus on unique identifiers:
* Project codes
* Client names
* Specific dates
### Check Spelling
Search requires correct spelling:
* Double-check names
* Try alternate spellings
* Use partial matches
### Use Filters
After searching:
* Narrow by type
* Filter by date
* Sort by relevance
{% hint style="warning" %}
What's Not Searched
* File contents (only file names)
* Archived items (by default)
{% endhint %}
Did this answer your question?
😞 😐 😃
# Projects Overview
## Projects Overview
Projects are the core of Kaana. They represent revenue initiatives, implementations, or any structured work your team is executing.
### What is a Project?
A project in Kaana contains:
* **Basic Information** — Title, description, status, dates
* **Test Cases** — Use case tests related to requirements
* **Milestones** — Key checkpoints and deadlines
* **Tasks** — Individual work items
* **Documents** — Associated files and resources
* **Activities** — Meeting notes, emails, and updates
* **Requirements** — Business requirements
* **Issues** — Blockers, bugs, and concerns
* **Team Members** — Assigned contacts and stakeholders
### Viewing Projects
#### Project List
Navigate to **Projects** to see all projects you have access to. The list shows:
* Project name and status
* Owner or lead
* Due date
* Progress indicators
#### Filtering Projects
Filter the project list by:
* **Status** — Active, On Hold, Completed, Cancelled
* **Owner** — Projects you own vs. all projects
* **Date Range** — Created or due date ranges
* **Tags** — Custom tags for organization
#### Sorting
Sort projects by:
* Name (A-Z or Z-A)
* Due date (nearest or furthest)
* Created date (newest or oldest)
* Status
### Project Details
Click on a project to view its details page.
{% stepper %}
{% step %}
### Overview Tab
* Project summary and description
* Key dates and milestones
* Status and progress
* Quick stats (tasks, issues, documents)
{% endstep %}
{% step %}
### Milestones Tab
* View and manage project milestones
* See tasks within each phase
* Track phase completion
{% endstep %}
{% step %}
### Tasks Tab
* All tasks for the project
* Filter by status, assignee, or phase
* Create new tasks
{% endstep %}
{% step %}
### Requirements Tab
* Business requirements
* Test cases
* Fit/gap analysis
{% endstep %}
{% step %}
### Documents Tab
* Attached files and resources
* Version history
* Upload new documents
{% endstep %}
{% step %}
### Activities Tab
* Meeting notes and logs
* Email records
* Team updates
{% endstep %}
{% step %}
### Issues Tab
* Linked issues and blockers
* Issue status tracking
* Create new issues
{% endstep %}
{% step %}
### History Tab
* Timeline of changes
* Who made what changes
* Audit trail
{% endstep %}
{% endstepper %}
### Project Status
| Status | Meaning |
| --------- | --------------------- |
| Active | Currently in progress |
| On Hold | Temporarily paused |
| Completed | Successfully finished |
| Cancelled | No longer proceeding |
# Project Milestones
Milestones mark important checkpoints and deadlines in your project.
## What is a Milestone?
A milestone is a significant point in your project timeline. Unlike tasks, milestones don't represent work to be done—they represent achievements or deadlines.
Examples of milestones:
* Project kickoff
* Phase completion
* Key deliverable due
* Client review meeting
* Go-live date
* Project closure
## Creating Milestones
{% stepper %}
{% step %}
Open your project, go to the Milestones tab, and click "+ Add Milestone".
{% endstep %}
{% step %}
Enter the details:
* Name — What this milestone represents
* Date — When it should be achieved
* Description — Additional context
{% endstep %}
{% step %}
Click Create.
{% endstep %}
{% endstepper %}
## Milestone Properties
| Property | Description |
| --------------- | ----------------------------- |
| **Name** | Title of the milestone |
| **Date** | Target date for achievement |
| **Description** | What this milestone means |
| **Status** | Upcoming, Achieved, or Missed |
## Tracking Milestones
### Milestone Status
| Status | Meaning |
| ------------ | --------------------------------------- |
| **Upcoming** | Date is in the future |
| **Achieved** | Milestone was met on or before the date |
| **Missed** | Date passed without achievement |
### Marking as Achieved
{% stepper %}
{% step %}
Open the milestone.
{% endstep %}
{% step %}
Click **Mark as Achieved**.
{% endstep %}
{% step %}
The achievement date is recorded.\
You can also set a milestone back to Upcoming if needed.
{% endstep %}
{% endstepper %}
## Viewing Milestones
### On the Project
* Milestones appear in the project overview
* They're shown on the project timeline
* Upcoming milestones are highlighted
### Dashboard
* Your dashboard may show upcoming milestones across all projects
## Linking Milestones
### Link to Tasks
{% stepper %}
{% step %}
Open the milestone.
{% endstep %}
{% step %}
Click **Link Tasks**.
{% endstep %}
{% step %}
Select relevant tasks and track progress toward the milestone.
{% endstep %}
{% endstepper %}
### Link to Issues
{% stepper %}
{% step %}
Open the milestone.
{% endstep %}
{% step %}
Click **Link Issue**.
{% endstep %}
{% step %}
Select blocking issues and monitor issue resolution.
{% endstep %}
{% endstepper %}
## Milestone Notifications
You receive notifications when:
* A milestone is approaching (configurable days before)
* A milestone is marked as achieved
* A milestone date is missed
## Best Practices
### Setting Milestone Dates
* Choose dates that are genuinely significant
* Don't create too many milestones
* Account for dependencies and buffers
### Naming Milestones
* Use clear, specific names
* Include what will be achieved
* Example: "UAT Sign-off Complete" not just "UAT"
### Tracking Progress
* Regularly review upcoming milestones
* Update status as things change
* Communicate early if a milestone is at risk
# Creating a Project
## Creating a Project
Learn how to create new projects in Kaana.
Updated over a month ago
### Quick Create
{% stepper %}
{% step %}
Click the **+ New Project** button from the Projects page or dashboard.
{% endstep %}
{% step %}
Enter a project title.
{% endstep %}
{% step %}
Click **Create**.
The project is created with default settings and you can fill in details later.
{% endstep %}
{% endstepper %}
### Detailed Create
For a more complete setup:
{% stepper %}
{% step %}
### Step 1: Basic Information
Click **+ New Project** and fill in the project details:
* **Title** — A clear, descriptive name
* **Description** — What this project is about
* **Status** — Usually starts as "Active"
* **Start Date** — When work begins
* **Due Date** — Target completion date
{% endstep %}
{% step %}
### Step 2: Team Assignment
* **Owner** — Primary person responsible
* **Team Members** — Add contacts who will work on this project
{% endstep %}
{% step %}
### Step 3: Organization Link
If this project is for a client:
* Select the **Organization** this project belongs to
This helps organize projects by client.
{% endstep %}
{% step %}
### Step 4: Tags and Categories
* Add **Tags** to categorize the project
* Tags help with filtering and reporting
{% endstep %}
{% step %}
### Step 5: Create
Click **Create Project** to finish.
{% endstep %}
{% endstepper %}
### Creating from a Template
Use an existing blueprint to jumpstart your project:
{% stepper %}
{% step %}
Click **+ New Project**
{% endstep %}
{% step %}
Click **Create from Template**
{% endstep %}
{% step %}
Browse available templates:
* **System Templates** — Pre-built templates from Kaana
* **My Templates** — Templates you've created
{% endstep %}
{% step %}
Select a template, customize the details, then click **Create**.
The project will include pre-configured phases, tasks, and milestones from the template.
{% endstep %}
{% endstepper %}
### Duplicating a Project
Copy an existing project:
{% stepper %}
{% step %}
Open the project you want to copy
{% endstep %}
{% step %}
Click the **...** menu and select **Duplicate Project**
{% endstep %}
{% step %}
Give the copy a new name and choose what to include:
* Phases and milestones
* Tasks
* Requirements
{% endstep %}
{% step %}
Click **Duplicate**
{% endstep %}
{% endstepper %}
### Best Practices
#### Naming Projects
* Use clear, descriptive names
* Include the client name if applicable
* Consider a naming convention for consistency
#### Setting Dates
* Set realistic start and due dates
* Account for dependencies between projects
* Leave buffer time for unexpected delays
#### Assigning Owners
* Every project should have a clear owner
* The owner is responsible for overall progress
* Owners receive notifications about their projects
#### Using Tags
* Create consistent tags across projects
* Examples: by department, project type, or priority
* Tags make reporting and filtering easier
### What Happens Next
After creating a project:
1. Add phases to structure the work
2. Create tasks for specific deliverables
3. Upload relevant documents
4. Add team members and contacts
5. Start logging activities
# Managing Tasks
Tasks are individual work items within a project. They help you track what needs to be done and who's responsible.
## Creating Tasks
### From the Project
{% stepper %}
{% step %}
### Open the project
Go to the project where you want to create the task.
{% endstep %}
{% step %}
### Go to the Tasks tab
Select the Tasks tab in the project.
{% endstep %}
{% step %}
### Create a new task
Click **+ New Task** and fill in the details:
* **Title** – What needs to be done
* **Description** – Additional details
* **Assignee** – Who's responsible
* **Due Date** – When it's due
* **Priority** – High, Medium, or Low
* **Phase** – Which project phase (optional)
{% endstep %}
{% step %}
### Create
Click **Create** to save the task.
{% endstep %}
{% endstepper %}
### Quick Add
{% stepper %}
{% step %}
Type the task title in the quick add input at the top of the task list.
{% endstep %}
{% step %}
Press Enter to create the task quickly.
{% endstep %}
{% step %}
Edit details later if needed.
{% endstep %}
{% endstepper %}
## Task Properties
| Property | Description |
| --------------- | ------------------------------------ |
| **Title** | Brief description of the work |
| **Description** | Detailed information or instructions |
| **Status** | Current state of the task |
| **Assignee** | Person responsible |
| **Due Date** | Deadline for completion |
| **Priority** | Importance level |
| **Phase** | Project phase this task belongs to |
| **Tags** | Categories for organization |
## Task Statuses
| Status | Meaning |
| --------------- | ---------------------------- |
| **Not Started** | Task hasn't begun |
| **In Progress** | Currently being worked on |
| **Blocked** | Waiting on something |
| **In Review** | Completed, awaiting approval |
| **Completed** | Finished |
## Updating Tasks
### Edit Task Details
{% stepper %}
{% step %}
Click on the task to open it.
{% endstep %}
{% step %}
Edit any field in the task.
{% endstep %}
{% step %}
Changes save automatically.
{% endstep %}
{% endstepper %}
### Change Status
* Click the status dropdown
* Select the new status
Status changes are logged in history.
### Reassign
{% stepper %}
{% step %}
Click the assignee field.
{% endstep %}
{% step %}
Search for or select a new person.
{% endstep %}
{% step %}
The new assignee is notified.
{% endstep %}
{% endstepper %}
## Organizing Tasks
### Drag and Drop
Reorder tasks by dragging them:
* Drag within a phase to reorder
* Drag between phases to move
* Priority and order are preserved
### Filtering
Filter the task list by:
* **Status** – Show only specific statuses
* **Assignee** – Tasks for specific people
* **Phase** – Tasks in specific phases
* **Priority** – High, Medium, or Low
* **Due Date** – Overdue, due today, due this week
### Grouping
Group tasks by:
* Phase
* Assignee
* Status
* Priority
## Linking Tasks
### Link to Issues
{% stepper %}
{% step %}
Open the task you want to link.
{% endstep %}
{% step %}
Click **Link Issue**.
{% endstep %}
{% step %}
Select or create an issue to link.
{% endstep %}
{% step %}
The link appears on both the task and the issue.
{% endstep %}
{% endstepper %}
### Link to Requirements
{% stepper %}
{% step %}
Open the task.
{% endstep %}
{% step %}
Click **Link Requirement**.
{% endstep %}
{% step %}
Select the requirement to connect.
{% endstep %}
{% step %}
Track which requirements each task addresses.
{% endstep %}
{% endstepper %}
## Task Notifications
You receive notifications when:
* A task is assigned to you
* A task you own is updated
* A task due date is approaching
* Someone mentions you in a task comment
## Comments on Tasks
Add comments to tasks for:
* Questions and clarifications
* Progress updates
* Decisions and approvals
### Adding a Comment
{% stepper %}
{% step %}
Open the task.
{% endstep %}
{% step %}
Scroll to the comments section.
{% endstep %}
{% step %}
Type your comment and use @mentions to notify specific people.
{% endstep %}
{% step %}
Click **Post** to publish the comment.
{% endstep %}
{% endstepper %}
## Deleting Tasks
{% stepper %}
{% step %}
Open the task you want to delete.
{% endstep %}
{% step %}
Click the **...** menu.
{% endstep %}
{% step %}
Select **Delete** and confirm the deletion.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Note**: Deleted tasks cannot be recovered.
{% endhint %}
# Activities Overview
Activities track interactions, communications, and updates related to your projects.
## What are Activities?
Activities log everything that happens on a project:
* **Meetings** - Scheduled calls and in-person meetings
* **Emails** - Important email communications
* **Notes** - Internal notes and memos
* **Updates** - Progress updates and announcements
* **Calls** - Phone conversations
## Viewing Activities
### Activity List
Navigate to **Activities** to see all activities across your projects. Activities are displayed in chronological order, with the most recent first.
### Project Activities
{% stepper %}
{% step %}
Open a project.
{% endstep %}
{% step %}
Go to the **Activities** tab.
{% endstep %}
{% step %}
See only activities for that project.
{% endstep %}
{% endstepper %}
### Filtering
Filter activities by:
* **Type** - Meetings, emails, notes, etc.
* **Project** - Specific project
* **Date Range** - When the activity occurred
* **Created By** - Who logged the activity
## Creating Activities
### Log an Activity
{% stepper %}
{% step %}
Navigate to **Activities** or a project's Activities tab.
{% endstep %}
{% step %}
Click **+ New Activity**.
{% endstep %}
{% step %}
Fill in the details:
* **Type** - Select the activity type
* **Title** - Brief description
* **Description** - Full details
* **Date** - When it occurred
* **Project** - Associate with a project
{% endstep %}
{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}
### Quick Log
{% stepper %}
{% step %}
From the dashboard or project, use the quick activity input.
{% endstep %}
{% step %}
Type a title.
{% endstep %}
{% step %}
Select the type.
{% endstep %}
{% step %}
Press Enter.
{% endstep %}
{% step %}
Add details later.
{% endstep %}
{% endstepper %}
## Activity Types
| Type | Use For |
| ------- | ------------------------------- |
| Meeting | Scheduled calls, demos, reviews |
| Email | Important email threads |
| Note | Internal notes and observations |
| Update | Progress announcements |
| Call | Phone conversations |
## Activity Details
Each activity includes:
* **Title** - Brief summary
* **Description** - Full content (supports rich text)
* **Type** - Category of activity
* **Date** - When it occurred
* **Created By** - Who logged it
* **Project** - Associated project
* **Comments** - Discussion thread
* **Linked Issues** - Related issues
## Mentioning People
{% stepper %}
{% step %}
Type `@` followed by their name.
{% endstep %}
{% step %}
Select from the dropdown.
{% endstep %}
{% step %}
They'll receive a notification.
{% endstep %}
{% endstepper %}
Example: `@John Smith please review this by Friday`
## Linking to Issues
{% stepper %}
{% step %}
Open the activity.
{% endstep %}
{% step %}
Click **Link Issue**.
{% endstep %}
{% step %}
Select an existing issue or create new.
{% endstep %}
{% step %}
The link appears on both records.
{% endstep %}
{% endstepper %}
## Comments on Activities
{% stepper %}
{% step %}
Open the activity.
{% endstep %}
{% step %}
Scroll to comments.
{% endstep %}
{% step %}
Type your comment.
{% endstep %}
{% step %}
Click **Post**.
{% endstep %}
{% endstepper %}
Comments support @mentions and formatting.
## Editing Activities
{% stepper %}
{% step %}
Open the activity.
{% endstep %}
{% step %}
Click **Edit**.
{% endstep %}
{% step %}
Update any field.
{% endstep %}
{% step %}
Changes save automatically.
{% endstep %}
{% endstepper %}
Changes are logged in the activity history.
## Deleting Activities
{% stepper %}
{% step %}
Open the activity.
{% endstep %}
{% step %}
Click the **...** menu.
{% endstep %}
{% step %}
Select **Delete**.
{% endstep %}
{% step %}
Confirm deletion.
{% endstep %}
{% endstepper %}
Note: This cannot be undone.
## Best Practices
### Logging Meetings
* Log meetings immediately after they occur
* Include key decisions and action items
* Link to relevant tasks or issues
### Using Notes
* Document important observations
* Record decisions that don't fit elsewhere
* Reference in future discussions
### Keeping Records
* Log significant emails for reference
* Create a paper trail for decisions
* Activities provide audit history
# Issues Overview
## Issues Overview
Issues help you track problems, blockers, and concerns that need resolution.
Updated over a month ago
### What are Issues?
Issues represent:
* **Bugs** - Technical problems
* **Blockers** - Things preventing progress
* **Risks** - Potential problems
* **Concerns** - Questions or uncertainties
* **Defects** - Quality issues
### Viewing Issues
#### Issue List
Navigate to **Issues** to see all issues in your organization.
The list shows:
* Issue title
* Status
* Priority
* Assigned project(s)
* Created date
#### Project Issues
{% stepper %}
{% step %}
Open a project.
{% endstep %}
{% step %}
Go to the **Issues** tab.
{% endstep %}
{% step %}
See issues linked to that project.
{% endstep %}
{% endstepper %}
#### Issue Groups
Issues can be organized into groups for better management:
* View issues by group
* Filter by group
* Create custom groups
### Creating Issues
#### Create an Issue
{% stepper %}
{% step %}
Navigate to **Issues** or a project's Issues tab.
{% endstep %}
{% step %}
Click **+ New Issue**.
{% endstep %}
{% step %}
Fill in the details:
* **Title** - Brief description of the issue
* **Description** - Full details
* **Priority** - Critical, High, Medium, Low
* **Group** - Category or type
* **Project** - Associated project (optional)
{% endstep %}
{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}
#### Quick Create
{% stepper %}
{% step %}
From the issues list, type in the quick input.
{% endstep %}
{% step %}
Press Enter.
{% endstep %}
{% step %}
Add details later.
{% endstep %}
{% endstepper %}
### Issue Properties
| **Property** | **Description** |
| ---------------- | --------------------------------- |
| **Title** | Brief description |
| **Description** | Full details and context |
| **Status** | Current state |
| **Priority** | Importance level |
| **Group** | Category or type |
| **Project(s)** | Linked projects |
| **Linked Items** | Related tasks, requirements, etc. |
### Issue Status
| **Status** | **Meaning** |
| --------------- | -------------------------------- |
| **Open** | Issue is active, needs attention |
| **In Progress** | Being worked on |
| **Pending** | Waiting for something |
| **Resolved** | Fixed or addressed |
| **Closed** | No longer active |
### Issue Priority
| **Priority** | **Meaning** |
| ------------ | ---------------------------- |
| **Critical** | Immediate attention required |
| **High** | Important, address soon |
| **Medium** | Normal priority |
| **Low** | Address when possible |
### Linking Issues
Issues can be linked to many items for traceability:
#### Link to Projects
* An issue can affect multiple projects
* Project teams see relevant issues
#### Link to Tasks
* Show which tasks are blocked
* Track issue resolution progress
#### Link to Requirements
* Connect issues to business requirements
* Impact assessment for changes
#### Link to Documents
* Reference relevant documentation
* Attach evidence or reports
#### Link to Activities
* Connect to meeting notes
* Reference discussions about the issue
### Creating Links
{% stepper %}
{% step %}
Open the issue.
{% endstep %}
{% step %}
Click **Link** and choose the item type.
{% endstep %}
{% step %}
Select the item to link.
{% endstep %}
{% step %}
View all links in the issue details.
{% endstep %}
{% endstepper %}
### Issue Groups
Organize issues by creating groups.
#### Create a Group
{% stepper %}
{% step %}
Go to **Issues**.
{% endstep %}
{% step %}
Click **Manage Groups**.
{% endstep %}
{% step %}
Click **+ New Group**.
{% endstep %}
{% step %}
Enter a name (e.g., "Technical Bugs", "Process Issues").
{% endstep %}
{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}
#### Assign to Group
{% stepper %}
{% step %}
When creating or editing an issue, select the **Group** dropdown.
{% endstep %}
{% step %}
Choose a group.
{% endstep %}
{% step %}
The issue appears under that group.
{% endstep %}
{% endstepper %}
### Updating Issues
{% stepper %}
{% step %}
Open the issue.
{% endstep %}
{% step %}
Edit any field.
{% endstep %}
{% step %}
Changes save automatically.
{% endstep %}
{% endstepper %}
Status changes are logged for audit purposes.
### Issue Heatmap
{% stepper %}
{% step %}
Open a project.
{% endstep %}
{% step %}
View the issue heatmap.
{% endstep %}
{% step %}
See patterns of issue creation and resolution.
{% endstep %}
{% step %}
Identify problem periods.
{% endstep %}
{% endstepper %}
### Best Practices
#### Writing Good Issue Titles
* Be general
* Example: "Authentication & SSO"
# Tags
Tags help you organize and categorize content across Kaana.
Updated over a month ago
## What are Tags?
Tags are labels you can apply to:
* Projects
* Documents
* Issues
* Other content
Use tags to:
* Organize similar items
* Enable quick filtering
* Create custom categories
* Improve searchability
## Viewing Tags
### Tag List
Go to **Settings** > **Tags** to see all tags.
Each tag shows:
* Tag name
* Color
* Category (if any)
* Usage count
## Creating Tags
### Add a Tag
{% stepper %}
{% step %}
Go to **Settings** > **Tags**.
{% endstep %}
{% step %}
Click **+ New Tag**.
{% endstep %}
{% step %}
Enter details:
* **Name** — Tag label
* **Color** — Visual identifier
* **Category** — Group for organization (optional)
{% endstep %}
{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}
### Quick Create
{% stepper %}
{% step %}
When tagging an item, start typing a tag name.
{% endstep %}
{% step %}
If it doesn't exist, click **Create "\[name]"**.
{% endstep %}
{% step %}
The tag is created and applied.
{% endstep %}
{% endstepper %}
## Tag Categories
Organize tags into categories.
### Create a Category
{% stepper %}
{% step %}
Go to **Settings** > **Tags**.
{% endstep %}
{% step %}
Click **Manage Categories**.
{% endstep %}
{% step %}
Click **+ New Category**.
{% endstep %}
{% step %}
Enter category name.
{% endstep %}
{% step %}
Click **Create**.
{% endstep %}
{% endstepper %}
### Assign Tags to Categories
{% stepper %}
{% step %}
Edit a tag.
{% endstep %}
{% step %}
Select a category from the dropdown.
{% endstep %}
{% step %}
Save.
{% endstep %}
{% endstepper %}
## Applying Tags
### Tag a Project
{% stepper %}
{% step %}
Open the project.
{% endstep %}
{% step %}
Find the **Tags** section.
{% endstep %}
{% step %}
Click **Add Tag**.
{% endstep %}
{% step %}
Select or search for tags.
{% endstep %}
{% step %}
Tags are applied immediately.
{% endstep %}
{% endstepper %}
### Tag Multiple Items
{% stepper %}
{% step %}
Select multiple items (checkboxes).
{% endstep %}
{% step %}
Click **Tag** in the bulk actions.
{% endstep %}
{% step %}
Select tags to apply.
{% endstep %}
{% step %}
Apply to all selected.
{% endstep %}
{% endstepper %}
## Filtering by Tags
### Filter Projects
{% stepper %}
{% step %}
Go to Projects.
{% endstep %}
{% step %}
Click **Filter**.
{% endstep %}
{% step %}
Select **Tags**.
{% endstep %}
{% step %}
Choose tags to filter by.
{% endstep %}
{% step %}
View matching projects.
{% endstep %}
{% endstepper %}
### Filter Other Content
Similar filtering is available for:
* Documents
* Issues
* Activities
## Editing Tags
{% stepper %}
{% step %}
Go to **Settings** > **Tags**.
{% endstep %}
{% step %}
Find the tag.
{% endstep %}
{% step %}
Click **Edit**.
{% endstep %}
{% step %}
Update name, color, or category.
{% endstep %}
{% step %}
Save changes.
Changes apply to all tagged items.
{% endstep %}
{% endstepper %}
## Deleting Tags
{% stepper %}
{% step %}
Go to **Settings** > **Tags**.
{% endstep %}
{% step %}
Find the tag.
{% endstep %}
{% step %}
Click **Delete**.
{% endstep %}
{% step %}
Confirm deletion.
The tag is removed from all items.
{% endstep %}
{% endstepper %}
## Merging Tags
Combine duplicate or similar tags.
{% stepper %}
{% step %}
Go to **Settings** > **Tags**.
{% endstep %}
{% step %}
Select tags to merge.
{% endstep %}
{% step %}
Click **Merge**.
{% endstep %}
{% step %}
Choose the target tag.
{% endstep %}
{% step %}
Confirm.
All items move to the target tag.
{% endstep %}
{% endstepper %}
## Tag Colors
Colors help visually identify tags:
* Choose from preset colors
* Use consistent colors for related tags
* Consider color-coding by category
## Best Practices
### Naming Tags
* Use clear, descriptive names
* Keep names short
* Be consistent with naming style
### Organizing Tags
* Create categories for related tags
* Limit the number of tags
* Review and clean up regularly
### Using Tags
* Tag items consistently
* Don't over-tag (3–5 tags maximum)
* Use tags that aid filtering
## Tag Maintenance
* Review unused tags periodically
* Merge duplicates
* Update as needs change
## Permissions
Managing tags requires:
* View tags: Most users
* Create tags: Members and above
* Delete/edit tags: Administrators
***
Related Articles
* [Issues Overview](/product/managing-projects/projects-overview/issues-overview)
* [Organizations Overview](/product/organizations-and-contacts/contacts-and-organizations/organizations-overview)
* [User Management](broken://pages/5f1762498dfa05132ee6651be5f95c5ece5c6240)
* [Roles & Permissions](broken://pages/7a3664d23450c042d7e7084f78947259f6049fcc)
* [Search Tips](/product/getting-started/search-tips)
# Test Cases
Test cases help you verify that requirements are being met and track testing progress.
## What are Test Cases?
Test cases are structured tests that:
* Verify requirements are implemented correctly
* Document testing procedures
* Track pass/fail results over time
* Provide evidence of quality
## Viewing Test Cases
### All Test Cases
Navigate to **All Test Cases** to see test cases across all projects.
### Project Test Cases
* Open a project
* Go to **Requirements** tab
* View test cases linked to each requirement
### Test Case Details
Each test case shows:
* Title and description
* Steps to execute
* Expected result
* Linked requirements
* Execution history
## Creating Test Cases
{% stepper %}
{% step %}
### From a Requirement
* Open a requirement
* Click **+ Add Test Case**
* Fill in the details:
* **Title** — What's being tested
* **Steps** — How to execute the test
* **Expected Result** — What should happen
* **Preconditions** — What must be true before testing
* Click **Create**
{% endstep %}
{% step %}
### Standalone Test Case
* Navigate to **All Test Cases**
* Click **+ New Test Case**
* Fill in details
* Link to requirements later
{% endstep %}
{% endstepper %}
## Test Case Properties
| Property | Description |
| ------------------- | ------------------------ |
| **Title** | Brief name of the test |
| **Description** | What this test validates |
| **Steps** | Step-by-step procedure |
| **Expected Result** | What should happen |
| **Preconditions** | Required setup |
| **Requirement** | Linked requirement(s) |
| **Status** | Current execution status |
## Executing Tests
{% stepper %}
{% step %}
### Run a Test
* Open the test case
* Click **Execute**
* Follow the steps
{% endstep %}
{% step %}
### Record the Result
Choose one of:
* **Pass** — Test succeeded
* **Fail** — Test failed
* **Blocked** — Could not execute
* **Skipped** — Intentionally not run
* Add notes about the execution
* Click **Save Result**
{% endstep %}
{% endstepper %}
## Test Execution History
{% stepper %}
{% step %}
* Open the test case
* Click **Execution History**
{% endstep %}
{% step %}
You will see all previous runs including:
* Date and time
* Result (pass/fail)
* Who executed
* Notes
{% endstep %}
{% endstepper %}
## Linking Test Cases
{% stepper %}
{% step %}
### Link to Requirements
* Open the test case
* Click **Link Requirement**
* Select one or more requirements
The link appears on both records.
{% endstep %}
{% step %}
### Link to Issues
When a test fails:
* Open the test case
* Click **Link Issue**
* Create or select an issue
Track issue resolution from the linked issue.
{% endstep %}
{% endstepper %}
## Editing Test Cases
{% stepper %}
{% step %}
* Open the test case
* Click **Edit**
* Update any field
Changes save automatically.
{% endstep %}
{% endstepper %}
## Deleting Test Cases
{% stepper %}
{% step %}
* Open the test case
* Click **...** menu
* Select **Delete**
* Confirm deletion
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Note: Execution history is also deleted when a test case is deleted.
{% endhint %}
## Test Coverage
Track which requirements have tests:
* View requirements with/without test cases
* Identify gaps in test coverage
* Prioritize creating tests for critical requirements
## Best Practices
### Writing Test Cases
* Write clear, specific steps
* Include expected results for each step
* Document any preconditions
* Make tests repeatable
### Test Organization
* Create one test case per scenario
* Group related tests
* Link to relevant requirements
### Execution Tracking
* Execute tests regularly
* Record all results (even skipped)
* Note any issues encountered
* Update tests when procedures change
# Requirements Overview
Requirements track business needs and how your project addresses them.
## What are Requirements?
Requirements represent:
* Business needs and objectives
* Functional requirements
* Technical specifications
* Compliance needs
* User stories
## Viewing Requirements
{% stepper %}
{% step %}
### Requirements List
Navigate to All Requirements or view them within a project:
* Open a project
* Go to the **Requirements** tab
{% endstep %}
{% step %}
### Requirement Details
Each requirement shows:
* Title and description
* Status (Fit, Gap, Partial)
* Priority
* Linked test cases
* Linked issues
* Comments
{% endstep %}
{% endstepper %}
## Creating Requirements
### Add a Requirement
{% stepper %}
{% step %}
* Open a project
* Go to the **Requirements** tab
* Click **+ New Requirement**
* Fill in the details:
* **Title** – Brief name
* **Description** – Full requirement text
* **Status** – Fit, Gap, or Partial
* **Priority** – Importance level
* **Category** – Type of requirement
* Click **Create**
{% endstep %}
{% endstepper %}
### Import from Excel
{% stepper %}
{% step %}
* Click **Import**
* Download the template
* Fill in your requirements
* Upload the completed file
* Review and confirm the import
{% endstep %}
{% endstepper %}
## Fit/Gap Analysis
Requirements can be marked with their implementation status:
| Status | Meaning |
| ----------------- | ------------------------------------------- |
| **Fit** | The system meets this requirement |
| **Gap** | The system does not meet this requirement |
| **Partial** | The system partially meets this requirement |
| **Not Evaluated** | Not yet assessed |
## Updating Status
{% stepper %}
{% step %}
* Open the requirement
* Click the status dropdown
* Select the appropriate status
* Add notes explaining the assessment
{% endstep %}
{% endstepper %}
## Linking Requirements
### Link to Issues
{% stepper %}
{% step %}
When a gap is identified:
* Open the requirement
* Click **Link Issue**
* Create or select an issue
* Track issue resolution
{% endstep %}
{% endstepper %}
### Link to Tasks
{% stepper %}
{% step %}
Connect implementation tasks:
* Open the requirement
* Click **Link Task**
* Select related tasks
* Track completion
{% endstep %}
{% endstepper %}
## Requirement Comments
{% stepper %}
{% step %}
Discuss requirements with your team:
* Open the requirement
* Scroll to comments
* Add questions, clarifications, or updates
* @mention team members
{% endstep %}
{% endstepper %}
## Editing Requirements
{% stepper %}
{% step %}
* Open the requirement
* Click **Edit**
* Update any field
* Changes save automatically
{% endstep %}
{% endstepper %}
## Deleting Requirements
{% stepper %}
{% step %}
* Open the requirement
* Click the **...** menu
* Select **Delete**
* Confirm deletion
Note: This removes linked test cases and cannot be undone.
{% endstep %}
{% endstepper %}
## Requirements History
{% stepper %}
{% step %}
* Open the requirement
* Click **History**
* See all changes with timestamps
* Track who made what changes
{% endstep %}
{% endstepper %}
## Best Practices
### Writing Requirements
* Be specific and measurable
* Use consistent terminology
* Include acceptance criteria
### Fit/Gap Analysis
* Review all requirements systematically
* Document reasons for each status
* Update as the project progresses
### Test Coverage
* Create test cases for critical requirements
* Ensure gaps have tests for verification
* Execute tests regularly
# Documents Overview
The Documents feature provides centralized storage and management for all your project files.
Updated over a month ago
## What are Documents?
Documents in Kaana are files you upload and associate with:
* Projects
* Organizations
* Activities
* Requirements
Supported file types include:
* PDF documents
* Microsoft Word (.docx)
* Microsoft Excel (.xlsx)
* Images (PNG, JPG)
* And more
## Viewing Documents
### Document Library
Navigate to **Documents** to see all documents you have access to.
The library shows:
* Document name
* Type/format
* Upload date
* Uploader
* Associated projects
### Filtering
Filter documents by:
* **Type** — PDFs, spreadsheets, images, etc.
* **Project** — Documents for specific projects
* **Date** — Upload date range
* **Uploader** — Who uploaded the file
### Searching
Use the search bar to find documents by:
* File name
* Description
* Tags
### Document Details
Click on a document to view:
* Full document information
* Preview (for supported types)
* Version history
* Associated projects and activities
* Comments
## Uploading Documents
### Single Upload
{% stepper %}
{% step %}
### Single upload
* Navigate to **Documents** or a project's Documents tab
* Click **+ Upload**
* Select a file from your computer
* Add details:
* **Name** — Display name for the document
* **Description** — What this document contains
* **Project** — Associate with a project (optional)
* Click **Upload**
{% endstep %}
{% endstepper %}
### Drag and Drop
* Drag files directly onto the documents area
* Multiple files can be uploaded at once
* Files are queued and uploaded in order
### From Project
{% stepper %}
{% step %}
### Upload from a project
* Open a project
* Go to the **Documents** tab
* Click **+ Upload** or drag files
* The document is automatically linked to the project
{% endstep %}
{% endstepper %}
## Document Versions
Kaana tracks version history for documents.
### Uploading a New Version
{% stepper %}
{% step %}
### Upload a new version
* Open the document
* Click **Upload New Version**
* Select the updated file
* Add version notes (optional)
* Click **Upload**
{% endstep %}
{% endstepper %}
### Viewing Version History
{% stepper %}
{% step %}
### View version history
* Open the document
* Click **Version History**
* See all versions with:
* Upload date
* Uploader
* Version notes
* Download any previous version
{% endstep %}
{% endstepper %}
## Linking Documents
### Link to Projects
{% stepper %}
{% step %}
### Link a document to additional projects
* Open the document
* Click **Link to Project**
* Select additional projects
{% endstep %}
{% endstepper %}
### Unlink from Projects
{% stepper %}
{% step %}
### Unlink a document from a project
* Open the document
* Find the project in the linked list
* Click the unlink icon
{% endstep %}
{% endstepper %}
## Downloading Documents
{% stepper %}
{% step %}
### Download a document
* Open the document
* Click **Download**
Or right-click in the document list and select **Download**.
{% endstep %}
{% endstepper %}
## Deleting Documents
{% stepper %}
{% step %}
### Delete a document
* Open the document
* Click the **...** menu
* Select **Delete**
* Confirm deletion
Note: Deleting removes all versions and cannot be undone.
{% endstep %}
{% endstepper %}
## Document Permissions
* View access depends on your project access
* Upload requires edit permissions
* Delete requires appropriate permissions
* Documents follow tenant isolation
***
Related Articles
* [Welcome to Kaana](broken://pages/611c8ed5f7f5e8bdd4f3edfea3e4ab13383bd471)
* [Projects Overview](/product/managing-projects/projects-overview)
* [Activities Overview](/product/managing-projects/projects-overview/activities-overview)
* [Requirements Overview](/product/managing-projects/requirements-overview)
* [Blueprints & Templates](/product/planning-and-resources/blueprints-and-templates)
Feedback: Did this answer your question?
😞 😐 😃
# Reports Overview
Copyright (c) 2023, Intercom, Inc. () with Reserved Font Name "Inter". This Font Software is licensed under the SIL Open Font License, Version 1.1.
## Reports Overview
Reports help you analyze project data, track progress, and share information with stakeholders.
### Accessing Reports
Navigate to **Reports** from the main menu to access analytics and exports.
### Available Reports
#### Project Status
View overall project health:
* Active projects count
* Projects by status
* Projects by timeline status (on track, at risk, delayed)
#### Task Analysis
Understand task distribution:
* Tasks by status
* Tasks by assignee
* Overdue tasks
* Completion trends
#### Activity Summary
Review team activity:
* Activities by type
* Activities over time
* Most active projects
### Filtering Reports
Customize report data by filtering:
* **Date Range** — Select the time period
* **Projects** — Include specific projects
* **Teams** — Filter by team members
* **Status** — Include specific statuses
### Visualizations
Reports include various charts:
* Bar charts
* Line graphs
* Pie charts
* Tables with sortable data
### Exporting Data
{% stepper %}
{% step %}
### Export to PDF
* Open the report
* Click **Export**
* Select **PDF**
* Choose layout options
* Download the file
{% endstep %}
{% step %}
### Export to Excel
* Open the report
* Click **Export**
* Select **Excel**
* Download the spreadsheet
{% endstep %}
{% step %}
### Scheduling Reports
Set up automatic report delivery (if enabled):
* Open the report
* Click **Schedule**
* Set frequency (daily, weekly, monthly)
* Add email recipients
* Save the schedule
{% endstep %}
{% endstepper %}
### Best Practices
#### Regular Review
* Check key reports weekly
* Monitor trends over time
* Act on concerning patterns
#### Stakeholder Reports
* Create reports tailored to audience
* Executives: high-level summaries
* Teams: detailed task reports
#### Data Accuracy
* Ensure data is up to date
* Update task and issue statuses
* Log activities consistently
***
Related Articles
* [Activities Overview](/product/managing-projects/projects-overview/activities-overview)
* [Issues Overview](/product/managing-projects/projects-overview/issues-overview)
* [Exporting Data](broken://pages/27619e790322536217f818d05db8b540117c1094)
* [Kaana Advisor (KAI)](broken://pages/5aa5993725478944ce04d217d9b0d4056185feb2)
* [Health Assessments](broken://pages/18d7dd16e895e6422419fb0683f6e7390dddd801)
Did this answer your question? 😞😐😃
If you'd like to provide feedback or need more help, please update your question or reach out through your support channels.
# Program Planner
## Program Planner
The Program Planner helps you create and manage high-level program plans across multiple projects.
### What is the Program Planner?
The Program Planner allows you to:
* Create program-level plans
* Organize work into plan items
* Track progress across initiatives
* Manage dependencies between items
### Viewing Program Plans
#### Plan List
Navigate to Program Planner to see your plans.\
Each plan shows:
* Plan name
* Description
* Number of items
* Created date
#### Plan Details
Click on a plan to view:
* All plan items
* Item ordering
* Progress status
* Dependencies
### Creating a Program Plan
{% stepper %}
{% step %}
### New Plan
* Navigate to **Program Planner**
* Click **+ New Plan**
* Enter the details:
* **Name** — Plan title
* **Description** — What this plan covers
* Click **Create**
{% endstep %}
{% endstepper %}
### Managing Plan Items
{% stepper %}
{% step %}
### Add Items
* Open the plan
* Click **+ Add Item**
* Fill in the details:
* **Title** — Item name
* **Description** — Details
* **Start Date** — When it begins
* **End Date** — Target completion
* **Status** — Current state
* Click **Add**
{% endstep %}
{% step %}
### Reorder Items
* Drag and drop items to change their order.
{% endstep %}
{% step %}
### Nested Items
* Drag an item onto another to create a sub-item
* Expand/collapse parent items
{% endstep %}
{% endstepper %}
### Edit Items
{% stepper %}
{% step %}
* Click on the item
* Update any field
* Changes save automatically
{% endstep %}
{% endstepper %}
### Delete Items
{% stepper %}
{% step %}
* Click the **...** menu on the item
* Select **Delete**
* Confirm deletion
{% endstep %}
{% endstepper %}
### Item Properties
| Property | Description |
| --------------- | -------------------- |
| **Title** | Item name |
| **Description** | Full details |
| **Start Date** | When work begins |
| **End Date** | Target completion |
| **Status** | Current state |
| **Order** | Position in the list |
### Item Status
| Status | Meaning |
| --------------- | ----------------- |
| **Not Started** | Work hasn't begun |
| **In Progress** | Currently active |
| **Completed** | Finished |
| **On Hold** | Paused |
### Editing Plans
{% stepper %}
{% step %}
* Open the plan
* Click **Edit Plan**
* Update name or description
* Save changes
{% endstep %}
{% endstepper %}
### Deleting Plans
{% stepper %}
{% step %}
* Open the plan
* Click **Delete Plan**
* Confirm deletion
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
Deleting a plan removes all items and cannot be undone.
{% endhint %}
### Best Practices
#### Plan Structure
* Keep plans focused on a single program
* Use clear, descriptive names
* Break large initiatives into multiple plans
#### Item Organization
* Order items logically
* Use nesting for related items
* Keep items at similar granularity
#### Status Tracking
* Update status regularly
* Review plans in team meetings
* Archive completed plans
# Blueprints & Templates
Blueprints are reusable project templates that help you start new projects quickly with pre-configured structures.
## What are Blueprints?
Blueprints contain:
* Pre-defined phases
* Task templates
* Milestone structures
* Standard configurations
Use blueprints to:
* Standardize project structures
* Save time on project setup
* Ensure consistency across projects
* Share best practices
## Types of Templates
### System Templates
Pre-built templates provided by Kaana:
* Industry-standard project structures
* Common implementation methodologies
* Best practice frameworks
### My Templates
Templates you create and save:
* Based on your successful projects
* Customized for your organization
* Available only to your team
## Viewing Templates
### Template Library
Navigate to **Blueprints** to see available templates.
Browse by:
* **System Templates** — Provided by Kaana
* **My Templates** — Created by you
### Template Details
Click on a template to see:
* Description and purpose
* Included phases
* Task structure
* Milestones
## Creating from Templates
### Use a Template
{% stepper %}
{% step %}
Navigate to **Blueprints**
{% endstep %}
{% step %}
Find the template you want
{% endstep %}
{% step %}
Click **Use Template**
{% endstep %}
{% step %}
Enter project details:
* Project name
* Dates
* Team members
{% endstep %}
{% step %}
Click **Create Project**
The new project includes all template content.
{% endstep %}
{% endstepper %}
## Creating Your Own Templates
### Save from Project
Turn a project into a template:
{% stepper %}
{% step %}
Open a well-structured project
{% endstep %}
{% step %}
Click the **...** menu
{% endstep %}
{% step %}
Select **Save as Template**
{% endstep %}
{% step %}
Name and describe your template
{% endstep %}
{% step %}
Click **Save**
{% endstep %}
{% endstepper %}
### Create New Template
Build a template from scratch:
{% stepper %}
{% step %}
Navigate to **Blueprints**
{% endstep %}
{% step %}
Click **+ New Template**
{% endstep %}
{% step %}
Add:
* Template name
* Description
* Phases
* Tasks
* Milestones
{% endstep %}
{% step %}
Click **Create**
{% endstep %}
{% endstepper %}
### AI-Assisted Creation
Use AI to generate template structure:
{% stepper %}
{% step %}
Click **+ New Template**
{% endstep %}
{% step %}
Select **Generate with AI**
{% endstep %}
{% step %}
Describe your project type
{% endstep %}
{% step %}
Review and modify suggestions
{% endstep %}
{% step %}
Save the template
{% endstep %}
{% endstepper %}
## Managing Templates
### Edit Templates
{% stepper %}
{% step %}
Open the template
{% endstep %}
{% step %}
Click **Edit**
{% endstep %}
{% step %}
Modify structure
{% endstep %}
{% step %}
Save changes
{% endstep %}
{% endstepper %}
### Template Versions
Templates maintain version history:
* See previous versions
* Restore earlier versions
* Track who made changes
## Delete Templates
{% stepper %}
{% step %}
Open the template
{% endstep %}
{% step %}
Click **Delete**
{% endstep %}
{% step %}
Confirm deletion
Note: System templates cannot be deleted.
{% endstep %}
{% endstepper %}
## Template Content
### Phases
Templates can include:
* Phase names
* Phase descriptions
* Order and structure
### Tasks
Template tasks have:
* Titles and descriptions
* Relative dates (e.g., "Day 1", "Week 2")
* Assignee placeholders
* Priority settings
### Milestones
Include key checkpoints:
* Milestone names
* Relative timing
* Descriptions
## Best Practices
### Creating Good Templates
* Base on successful projects
* Include clear descriptions
* Set appropriate defaults
* Test before sharing
### Template Naming
* Use clear, descriptive names
* Include version or date if needed
* Indicate scope or type
### Keeping Templates Current
* Review templates regularly
* Update based on lessons learned
* Remove outdated templates
### Standardization
* Use consistent naming conventions
* Align with organizational standards
* Document template purposes
# Playbooks
## Playbooks
Playbooks are step-by-step guides and procedures for common processes and workflows.
### What are Playbooks?
Playbooks provide:
* Documented procedures
* Step-by-step instructions
* Best practice guides
* Standard operating procedures
Unlike blueprints (which are project templates), playbooks are instructional guides.
### Types of Playbooks
#### System Playbooks
Pre-built guides provided by Kaana:
* Common business processes
* Best practice procedures
* Getting started guides
#### My Playbooks
Playbooks you create:
* Custom procedures for your team
* Organization-specific guides
* Lessons learned documentation
### Viewing Playbooks
#### Playbook Library
Navigate to **Playbooks** to browse available guides.
Filter by:
* **System Playbooks** — Provided by Kaana
* **My Playbooks** — Created by you
#### Playbook Content
Open a playbook to see:
* Title and description
* Step-by-step instructions
* Related resources
* Version information
### Using Playbooks
#### Follow a Playbook
{% stepper %}
{% step %}
### Open the playbook
{% endstep %}
{% step %}
### Read through the steps
{% endstep %}
{% step %}
### Follow instructions in order
{% endstep %}
{% step %}
### Reference as needed
{% endstep %}
{% endstepper %}
#### Reference During Work
Keep playbooks handy while working:
* Open in a separate tab
* Print for reference
* Share with team members
### Creating Playbooks
#### New Playbook
{% stepper %}
{% step %}
### Navigate to Playbooks
{% endstep %}
{% step %}
### Click **+ New Playbook**
{% endstep %}
{% step %}
### Enter details
* **Title** — Playbook name
* **Description** — What this covers
* **Content** — Step-by-step instructions
{% endstep %}
{% step %}
### Click **Create**
{% endstep %}
{% endstepper %}
#### Content Structure
Organize playbook content with:
* Numbered steps
* Section headings
* Bullet points
* Notes and tips
#### Rich Formatting
Playbooks support:
* Bold and italic text
* Headings and subheadings
* Lists (numbered and bulleted)
* Links to resources
### Managing Playbooks
#### Edit Playbooks
{% stepper %}
{% step %}
### Open the playbook
{% endstep %}
{% step %}
### Click **Edit**
{% endstep %}
{% step %}
### Update content
{% endstep %}
{% step %}
### Save changes
{% endstep %}
{% endstepper %}
#### Playbook Versions
Track changes over time:
* View version history
* See who made changes
* Restore previous versions
#### Delete Playbooks
{% stepper %}
{% step %}
### Open the playbook
{% endstep %}
{% step %}
### Click **Delete**
{% endstep %}
{% step %}
### Confirm deletion
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
System playbooks cannot be deleted.
{% endhint %}
### Sharing Playbooks
Playbooks are visible to your organization:
* Team members can view
* Admins can edit
* Share links to specific playbooks
### Best Practices
#### Writing Playbooks
* Use clear, simple language
* Number all steps
* Include all necessary details
* Add screenshots if helpful
#### Organizing Content
* Start with an overview
* Group related steps
* Use consistent formatting
* End with next steps or cleanup
#### Maintaining Playbooks
* Review regularly for accuracy
* Update when processes change
* Archive obsolete playbooks
* Gather feedback from users
#### Playbook Naming
* Use action-oriented titles
* Be specific about the process
* Include scope or context
* Example: "New Client Onboarding Process"
# Contacts & Organizations
Manage your customers, partners, and vendors.
# Organizations Overview
Organizations represent your clients, partners, or business entities you work with.
Updated over a month ago
## What are Organizations?
An organization in Kaana represents:
* Client companies
* Partner organizations
* Vendors or suppliers
* Internal departments
* Any business entity you manage
## Viewing Organizations
### Organization List
Navigate to **Organizations** to see all organizations.
The list shows:
* Organization name
* Type (Client, Partner, Vendor, etc.)
* Primary contact
* Number of projects
* Status
### Filtering
Filter organizations by:
* **Type** — Client, partner, vendor, internal
* **Status** — Active or inactive
* **Has Projects** — With or without active projects
### Searching
Search by:
* Organization name
* Contact name
* Description
## Organization Details
Click on an organization to view:
### Overview
* Name and description
* Type and status
* Address and contact info
* Key metrics
### Projects Tab
* All projects for this organization
* Project status summary
* Quick access to project details
### Contacts Tab
* People associated with this organization
* Roles and contact information
* Add or remove contacts
### Documents Tab
* Documents linked to this organization
* Shared resources
* Organization-specific files
### Activities Tab
* Activity history
* Recent interactions
* Meeting notes and communications
### Tasks Tab
* Organization-level tasks
* Cross-project work items
### History Tab
* Timeline of changes
* Audit trail
## Creating Organizations
{% stepper %}
{% step %}
### Add an Organization
* Navigate to **Organizations**
* Click **+ New Organization**
* Fill in the details:
* **Name** — Organization name
* **Type** — Client, partner, vendor, internal
* **Description** — About this organization
* **Website** — Company website
* **Industry** — Business sector
* **Address** — Location information
* Click **Create**
{% endstep %}
{% endstepper %}
## Managing Contacts
{% stepper %}
{% step %}
### Add a Contact
* Open the organization
* Go to the **Contacts** tab
* Click **+ Add Contact**
* Either:
* Select an existing contact, or
* Create a new contact
* Set their role at this organization
{% endstep %}
{% step %}
### Remove a Contact
* Open the organization contacts
* Find the contact
* Click **Remove**
* Confirm removal
Note: This removes the association, not the contact record.
{% endstep %}
{% endstepper %}
## Organization Projects
{% stepper %}
{% step %}
### View Projects
* Open the organization
* Go to the **Projects** tab
{% endstep %}
{% step %}
### Create a Project
* From the organization, click **+ New Project**
* The project is automatically linked to this organization
{% endstep %}
{% step %}
### Link Existing Project
* Open the project
* In project settings, select the organization
{% endstep %}
{% endstepper %}
## Duplicating Organizations
{% stepper %}
{% step %}
* Open the organization
* Click the **...** menu
* Select **Duplicate**
* Modify the details
{% endstep %}
{% step %}
* Choose what to copy:
* Contacts
* Settings
* Click **Create**
{% endstep %}
{% endstepper %}
## Organization Status
| Status | Meaning |
| ------------ | ------------------- |
| **Active** | Currently engaged |
| **Inactive** | No current activity |
| **Prospect** | Potential client |
| **Former** | Past relationship |
## Editing Organizations
{% stepper %}
{% step %}
* Open the organization
* Click **Edit**
* Update any field
* Changes save automatically
{% endstep %}
{% endstepper %}
## Deleting Organizations
{% stepper %}
{% step %}
* Open the organization
* Click the **...** menu
* Select **Delete**
* Confirm deletion
Note: You cannot delete organizations with active projects.
{% endstep %}
{% endstepper %}
## Best Practices
### Naming
* Use official company names
* Be consistent with formatting
* Include "Inc.", "LLC" etc. if relevant
### Contacts
* Keep contact information current
* Mark primary contacts clearly
* Remove outdated contacts
### Tracking
* Log activities for audit trail
* Link relevant documents
* Maintain organization history
***
Related Articles
*
*
*
*
*
Did this answer your question?
Please indicate your feedback (sad, neutral, happy).
# Contacts Overview
Copyright (c) 2023, Intercom, Inc. () with Reserved Font Name "Inter".\
This Font Software is licensed under the SIL Open Font License, Version 1.1.
## Contacts Overview
Contacts are the people you work with—team members, clients, partners, and stakeholders.
### What are Contacts?
A contact in Kaana represents:
* Team members and colleagues
* Client stakeholders
* Vendor representatives
* External consultants
* Any person you interact with
### Contact Types
| Type | Description |
| ------------ | ------------------------------------- |
| **Internal** | Your organization's employees |
| **External** | Outside parties (clients, vendors) |
| **Client** | Customer contacts |
| **Vendor** | Supplier or service provider contacts |
### Viewing Contacts
#### Contact Directory
Navigate to **Contacts** to see all contacts. The directory shows:
* Name
* Email
* Phone
* Company
* Type
#### Filtering
Filter contacts by:
* **Type** — Internal, external, client, vendor
* **Company** — Specific organization
* **Active Status** — Active or inactive
#### Searching
Search by:
* Name
* Email
* Company
* Phone number
#### Contact Details
Click on a contact to view:
* Full name and title
* Contact information (email, phone)
* Company and department
* Organization associations
* Project involvement
* Activity history
### Creating Contacts
#### Add a Contact
{% stepper %}
{% step %}
### Add a Contact
Navigate to **Contacts**, click **+ New Contact**, fill in the details, then click **Create**.
{% endstep %}
{% step %}
### Fields to fill
* **Full Name** — Person's name
* **Email** — Email address
* **Phone** — Phone number
* **Company** — Where they work
* **Title** — Job title
* **Department** — Their department
* **Type** — Internal, external, client, vendor
{% endstep %}
{% endstepper %}
#### Quick Add
{% stepper %}
{% step %}
### Quick Add
When adding contacts elsewhere (projects, organizations), click **+ Add Contact** then **Create New**.
{% endstep %}
{% step %}
### Minimum details
Enter minimum details; complete the profile later.
{% endstep %}
{% endstepper %}
### Linking Contacts
#### To Organizations
{% stepper %}
{% step %}
### Link a Contact to an Organization
Open the contact and click **Link to Organization**.
{% endstep %}
{% step %}
### Select and Set Role
Select the organization and set their role.
{% endstep %}
{% endstepper %}
#### To Projects
{% stepper %}
{% step %}
### Add Contact to a Project Team
Open the project, go to **Team** or **Contacts**, then click **Add Member**.
{% endstep %}
{% step %}
### Select Contact
Select the contact to add them to the project.
{% endstep %}
{% endstepper %}
### Contact Roles
When linking contacts, specify their role:
* Project Manager
* Technical Lead
* Executive Sponsor
* Subject Matter Expert
* Stakeholder
* Custom roles
### Editing Contacts
{% stepper %}
{% step %}
### Edit a Contact
Open the contact and click **Edit**.
{% endstep %}
{% step %}
### Update Fields
Update any field. Changes save automatically.
{% endstep %}
{% endstepper %}
### Deactivating Contacts
{% stepper %}
{% step %}
### Deactivate a Contact
Open the contact and click **Edit**.
{% endstep %}
{% step %}
### Toggle Active
Toggle **Active** to off. The contact is hidden from active lists but preserved.
{% endstep %}
{% endstepper %}
### Deleting Contacts
{% stepper %}
{% step %}
### Delete a Contact
Open the contact, click the **...** menu, and select **Delete**.
{% endstep %}
{% step %}
### Confirm Deletion
Confirm deletion. Note: This removes all associations and cannot be undone.
{% endstep %}
{% endstepper %}
### Importing Contacts
{% stepper %}
{% step %}
### Start Import
Go to **Contacts** and click **Import**.
{% endstep %}
{% step %}
### Use Template
Download the template, fill in your contacts, then upload the file.
{% endstep %}
{% step %}
### Review & Confirm
Review the import and confirm.
{% endstep %}
{% endstepper %}
### Best Practices
#### Keeping Data Current
* Update contact info when it changes
* Deactivate contacts who leave organizations
* Verify email addresses
#### Avoiding Duplicates
* Search before creating new contacts
* Merge duplicates when found
* Use consistent naming
#### Complete Profiles
* Include email at minimum
* Add phone for key contacts
* Specify company and title
#### Organization Links
* Link contacts to their organizations
* Update when people change companies
* Track multiple affiliations
***
Related Articles:
*
*
*
*
*
Did this answer your question?
😞 😐 😃
# System Feed Overview
The System Feed provides AI-powered monitoring and insights for your connected integrations, helping you stay ahead of issues before they impact your business.
### What Is the System Feed?
When you connect Kaana to your billing and CRM systems (Zuora, Salesforce, Stripe), the System Feed automatically monitors for problems and generates actionable signals. Think of it as a command center for your revenue operations health.
### How It Works
1. **Connect Integrations** - Link your Zuora, Salesforce, or Stripe accounts in Settings > Integrations
2. **Automatic Monitoring** - Detection rules check your systems on a schedule (every 30 minutes by default)
3. **AI Analysis** - Kaana analyzes problems and provides recommendations
4. **Actionable Signals** - Get clear signals with steps to resolve issues
### Key Concepts
#### Signals
Signals are the issues and anomalies detected in your connected systems. Each signal includes:
* What the issue is
* Which entities are affected
* Severity level (Critical, Warning, Info)
* AI-generated recommendations
* Actions you can take
#### Detection Rules
Detection rules define what patterns to look for in your data. Kaana provides 18 pre-built system rules, and you can create custom rules for your specific needs.
See [Detection Rules](/guides/detection-rule-guides/guide-building-your-own-detection-rules) for details.
#### Kai Resolution Agent
Kai is Kaana's AI-powered resolution agent that can analyze signals and help fix issues directly in your connected systems.
See [Kai Resolution Agent](/ai-integrations/ai-resolution/kai-resolution-agent) for details.
### What We Monitor
Below is a brief list of the types of systems and data we monitor.
{% hint style="info" %}
Please note: This list is continuously updated as new system integrations and detection rules are implemented.
{% endhint %}
#### Zuora (Billing Platform)
| Issue Type | What It Means |
| --------------------------- | ------------------------------------------------- |
| **Failed Invoices** | Invoices that couldn't be generated or posted |
| **Failed Payments** | Payment collection attempts that were declined |
| **Failed Bill Runs** | Scheduled billing jobs that didn't complete |
| **Failed Payment Runs** | Scheduled payment collection that didn't complete |
| **Usage Processing Errors** | Usage-based billing records that failed |
| **Rating Errors** | Problems calculating prices for charges |
| **API Issues** | Connection problems with Zuora |
| **High Cancellations** | Unusual number of subscription cancellations |
| **Outstanding Balances** | Accounts with unpaid balances |
#### Salesforce (CRM)
| Issue Type | What It Means |
| ----------------------- | ------------------------------------------------------- |
| **Stuck Opportunities** | Deals that haven't been updated in 2+ weeks |
| **At-Risk Deals** | High-value deals closing soon but still in early stages |
| **Escalated Cases** | Support tickets marked as escalated |
| **Cold Leads** | Leads that haven't been worked in 30+ days |
#### Stripe (Payments)
| Issue Type | What It Means |
| -------------------------- | --------------------------------------------- |
| **Failed Payments** | Payment attempts that need new payment method |
| **Uncollectible Invoices** | Invoices that couldn't be collected |
| **Active Disputes** | Chargebacks that need response |
| **Past Due Subscriptions** | Subscriptions with overdue payments |
### Signal Severity Levels
| Level | Color | Meaning |
| ------------ | ------ | ------------------------------------------ |
| **Critical** | Red | Immediate action required - revenue impact |
| **Warning** | Yellow | Should be addressed soon |
| **Info** | Blue | For awareness, no action needed |
### Using the System Feed
#### Dashboard View
Access the System Feed from the main navigation. The dashboard shows:
* Total active signals
* Breakdown by severity
* Signals by integration type
* Trend charts
#### Feed View
The Feed shows individual signals with:
* Signal title and description
* Affected entities (invoices, accounts, etc.)
* AI-generated recommendations
* Available actions
#### Analyze Button
Click **Analyze** to trigger a fresh scan of your integrations. This:
1. Connects to your systems
2. Checks for current issues using active detection rules
3. Generates new signals
4. Updates the feed
### Taking Action on Signals
Each signal provides several options:
| Action | Description |
| -------------------- | -------------------------------------------------- |
| **View Details** | See full signal information |
| **Resolve with Kai** | Get AI-assisted resolution (requires plan feature) |
| **Ask Kai** | Get AI analysis and recommendations |
| **Assign** | Delegate the issue to a team member |
| **Add Comment** | Leave notes or updates |
| **View History** | See the full audit trail |
| **Link to Ticket** | Connect to a support ticket |
### Signal Status Lifecycle
Signals track issues through their entire lifecycle:
| Status | Meaning |
| ---------------- | ------------------------------ |
| **Active** | New issue requiring attention |
| **Acknowledged** | Team has seen the issue |
| **Assigned** | Delegated to a specific person |
| **In Progress** | Being actively worked on |
| **Resolved** | Issue has been fixed |
| **Dismissed** | Issue is not actionable |
#### Deduplication
Unlike one-time notifications, signals are persistent and deduplicated:
* If the same issue is detected again, the existing signal is updated
* Detection count shows how many times the issue has recurred
* If a resolved issue returns, it's automatically reopened
#### Assignment
You can assign signals to team members:
* Assigning changes status to "Assigned"
* Assignees see their signals in their personal view
* Assignment history is tracked
#### Comments & History
Every action on a signal is recorded:
* Status changes
* Assignments
* Comments from team members
* Resolution agent actions
This provides a complete audit trail for compliance and review.
### Requirements
* **Active Integration** - Your integration must be connected and active
* **Valid Credentials** - API credentials must be current
* **Plan Feature** - System Feed requires Starter plan or higher; AI features require Advanced plan
### Data Privacy
* Kaana only reads data needed for monitoring
* Write access is only used when you explicitly trigger resolution actions
* Signal data is stored securely and scoped to your organization
* See [Data Privacy](/support/security-and-privacy/data-privacy) for details
# System Feed Ingestion
The System Feed uses two approaches for data ingestion:
**1. Detection Rules** (runs every 30 minutes)
* Custom detection rules you create in the UI
* Uses the pipeline: Source → Filter → Aggregate → Evaluate → Fingerprint → Store
* Executes against your linked integrations (Zuora, Stripe, Salesforce, etc.)
**2. AI-powered Anomaly Detection** (runs every 15 minutes)
* Automatic pattern detection across ingested events
* Uses AI to generate alerts from detected anomalies
* Auto-resolves alerts when issues are fixed
Both approaches feed into the same System Feed. The detection rules give you precise, configurable control over what to monitor, while the AI system catches patterns you might not have explicitly defined.
| Source | Schedule | How It Works |
| ------------------------ | ------------ | --------------------------------------------------- |
| **Detection Rules** | Every 30 min | Runs your configured rules against integration data |
| **AI Anomaly Detection** | Every 15 min | AI analyzes event patterns and generates alerts |
So if you create a detection rule for "Failed Payments > 5", that runs via the rules engine. Meanwhile, the AI system might independently detect unusual payment failure patterns even without a specific rule.
# Managed Services Overview
Managed Services provide dedicated support and expertise for your key business platforms.
Updated over a month ago
## What are Managed Services?
Managed Services are add-on offerings that provide:
* Expert support for specific platforms
* Proactive monitoring and alerts
* AI-powered insights and recommendations
* Issue resolution assistance
## Available Services
### Zuora Managed Services
Expert support for Zuora subscription management:
* Billing configuration
* Revenue recognition
* Subscription analytics
### Salesforce Managed Services
Support for Salesforce CRM:
* Configuration optimization
* Integration support
* Data management
### Nue Managed Services
Assistance with Nue platform:
* Setup and configuration
* Best practices
* Troubleshooting
### Stripe Billing Managed Services
Support for Stripe billing:
* Payment configuration
* Subscription management
* Reporting setup
## Service Tiers
Each managed service offers three tiers:
### Growth Tier
* Basic support coverage
* Standard response times
* Core monitoring features
### Scale Tier
* Extended support hours
* Faster response times
* Advanced monitoring
* Proactive recommendations
### Premier Tier
* 24/7 support coverage
* Priority response
* Dedicated support contact
* Custom integrations
* Strategic guidance
## Subscribing to Managed Services
### Add a Service
{% stepper %}
{% step %}
### Go to Billing settings
Go to **Settings** > **Billing**.
{% endstep %}
{% step %}
### Open Managed Services
Click **Managed Services**.
{% endstep %}
{% step %}
### Select service
Select the service you want to add.
{% endstep %}
{% step %}
### Choose a tier
Choose the appropriate tier for your needs.
{% endstep %}
{% step %}
### Review pricing
Review the pricing details for the selected service and tier.
{% endstep %}
{% step %}
### Subscribe
Click **Subscribe**.
{% endstep %}
{% endstepper %}
### Manage Subscriptions
{% stepper %}
{% step %}
### View billing settings
Go to **Settings** > **Billing**.
{% endstep %}
{% step %}
### See active services
See your active managed services.
{% endstep %}
{% step %}
### Change subscription
Upgrade, downgrade, or cancel a service as needed.
{% endstep %}
{% endstepper %}
## Using Managed Services
### Concierge Dashboard
{% stepper %}
{% step %}
### Navigate to Managed Services
Open the **Managed Services** section.
{% endstep %}
{% step %}
### View status
View overall service status.
{% endstep %}
{% step %}
### See alerts
See active alerts.
{% endstep %}
{% step %}
### Access AI recommendations
Access AI-driven recommendations and insights.
{% endstep %}
{% endstepper %}
### AI Concierge
The AI Concierge provides:
* Automated Alerts — Notifications about issues
* Insights — Analysis of your platform usage
* Recommendations — Suggested improvements
* Remediation Actions — Proposed fixes
### Service Requests
{% stepper %}
{% step %}
### Open Managed Services
Go to **Managed Services**.
{% endstep %}
{% step %}
### Create new request
Click **New Request**.
{% endstep %}
{% step %}
### Describe issue
Describe your issue or question in detail.
{% endstep %}
{% step %}
### Submit
Submit the request.
{% endstep %}
{% step %}
### Track status
Track the status and responses for your request.
{% endstep %}
{% endstepper %}
### Activity Feed
View all managed service activity:
* Alert notifications
* Request updates
* AI recommendations
* Resolution notes
## Alerts
### Alert Severity
| Severity | Meaning |
| -------- | ---------------------------- |
| Critical | Immediate attention required |
| High | Address soon |
| Medium | Monitor and plan |
| Low | Informational |
### Responding to Alerts
{% stepper %}
{% step %}
### View alert details
Open the alert to see full details.
{% endstep %}
{% step %}
### Review recommendations
Review AI recommendations provided for the alert.
{% endstep %}
{% step %}
### Take action
Accept or dismiss suggestions and take remediation actions.
{% endstep %}
{% step %}
### Track resolution
Track the resolution status until the issue is closed.
{% endstep %}
{% endstepper %}
## Integration Monitoring
For connected integrations:
* View connection health
* See sync status
* Monitor error rates
* Get proactive alerts
## Best Practices
### Proactive Monitoring
* Review alerts regularly
* Act on critical issues promptly
* Use AI recommendations
### Service Requests
* Provide detailed descriptions
* Include relevant context
* Follow up on open requests
### Tier Selection
* Match tier to your needs
* Consider anticipated growth
* Evaluate required response times
***
Related Articles
*
*
*
*
*
Copyright (c) 2023, Intercom, Inc. () with Reserved Font Name "Inter". This Font Software is licensed under the SIL Open Font License, Version 1.1.
# Subscription Plans
Copyright (c) 2023, Intercom, Inc. () with Reserved Font Name "Inter".\
This Font Software is licensed under the SIL Open Font License, Version 1.1.
## Subscription Plans
Learn about the available plans and features
### Available Plans
For the latest information on Kaana subscription plans, please visit our website:
### Pricing
Visit our pricing page for current rates:
* Monthly billing available
* Annual billing with discount
* Custom pricing for enterprise
### Choosing a Plan
#### Consider Your Needs
* Team Size — How many people need access?
* Features — Which features do you need?
* Growth — Will you add users soon?
#### Start Small
* Begin with what you need
* Upgrade as you grow
* Downgrade if needed
### Changing Plans
#### Upgrade
{% stepper %}
{% step %}
Go to **Profile Icon (top right)** → **Billing**
{% endstep %}
{% step %}
Click **Change Plan**
{% endstep %}
{% step %}
Select your new plan
{% endstep %}
{% step %}
Review changes
{% endstep %}
{% step %}
Confirm upgrade
Upgrades take effect immediately.
{% endstep %}
{% endstepper %}
#### Downgrade
{% stepper %}
{% step %}
Go to **Profile Icon (top right)** → **Billing**
{% endstep %}
{% step %}
Click **Change Plan**
{% endstep %}
{% step %}
Select your new plan
{% endstep %}
{% step %}
Review what changes
{% endstep %}
{% step %}
Confirm downgrade
Downgrades take effect at next billing cycle.
{% endstep %}
{% endstepper %}
#### Adding Seats
{% stepper %}
{% step %}
Go to **Profile Icon (top right)** → **Billing**
{% endstep %}
{% step %}
Click **Add Seats**
{% endstep %}
{% step %}
Enter the number to add
{% endstep %}
{% step %}
Review prorated cost
{% endstep %}
{% step %}
Confirm
New seats are available immediately.
{% endstep %}
{% endstepper %}
### Enterprise Plans
For large organizations:
* Custom seat counts
* Dedicated support
* Custom integrations
* SLA agreements
* Volume discounts
Contact sales for enterprise pricing.
### Related Articles
*
*
*
*
*
Did this answer your question?
😞 😐 😃
# Managing Your Subscription
Learn how to manage your Kaana subscription.
Updated over a month ago
## Accessing Billing
{% stepper %}
{% step %}
### Access Billing
* Go to your profile icon in the top right of the page
* Select **Billing**
Note: Requires Owner role.
{% endstep %}
{% endstepper %}
## Subscription Overview
View your current subscription:
* Current plan
* Billing cycle (monthly/annual)
* Next billing date
* Number of seats
* Current cost
## Changing Your Plan
### Upgrade
{% stepper %}
{% step %}
Click **Change Plan**
{% endstep %}
{% step %}
Select the new plan
{% endstep %}
{% step %}
Review what's included
{% endstep %}
{% step %}
See price difference
{% endstep %}
{% step %}
Click **Upgrade**
{% endstep %}
{% endstepper %}
Upgrades are effective immediately. You'll be charged the prorated difference.
### Downgrade
{% stepper %}
{% step %}
Click **Change Plan**
{% endstep %}
{% step %}
Select the new plan
{% endstep %}
{% step %}
Review what you'll lose
{% endstep %}
{% step %}
Click **Downgrade**
{% endstep %}
{% endstepper %}
Downgrades take effect at the end of your current billing period.
## Managing Seats
### Add Seats
{% stepper %}
{% step %}
Click **Add Seats**
{% endstep %}
{% step %}
Enter how many to add
{% endstep %}
{% step %}
See prorated cost
{% endstep %}
{% step %}
Click **Add**
{% endstep %}
{% endstepper %}
New seats are available immediately.
### Remove Seats
{% stepper %}
{% step %}
Click **Remove Seats**
{% endstep %}
{% step %}
Enter how many to remove
{% endstep %}
{% step %}
Note: Must deactivate users first
{% endstep %}
{% step %}
Click **Remove**
{% endstep %}
{% endstepper %}
Changes take effect at next billing cycle.
## Billing Cycle
### Switch to Annual
{% stepper %}
{% step %}
Click **Switch to Annual**
{% endstep %}
{% step %}
Review annual price
{% endstep %}
{% step %}
See your savings
{% endstep %}
{% step %}
Confirm change
{% endstep %}
{% endstepper %}
Save money with annual billing. Changes apply at next renewal.
### Switch to Monthly
{% stepper %}
{% step %}
Click **Switch to Monthly**
{% endstep %}
{% step %}
Review monthly price
{% endstep %}
{% step %}
Confirm change
{% endstep %}
{% endstepper %}
Changes apply at next renewal.
## Payment History
### View Invoices
{% stepper %}
{% step %}
Go to Billing
{% endstep %}
{% step %}
Click **Payment History**
{% endstep %}
{% step %}
See all past invoices
{% endstep %}
{% step %}
Download PDFs
{% endstep %}
{% endstepper %}
### Invoice Details
Each invoice shows:
* Invoice date
* Amount
* Payment status
* Items included
## Pause Subscription
{% stepper %}
{% step %}
Click **Pause Subscription**
{% endstep %}
{% step %}
Select pause duration
{% endstep %}
{% step %}
Confirm
{% endstep %}
{% endstepper %}
During pause:
* Access is limited
* Data is preserved
* Billing stops
Resume anytime to restore access.
## Cancel Subscription
{% stepper %}
{% step %}
Click **Cancel Subscription**
{% endstep %}
{% step %}
Provide reason (optional)
{% endstep %}
{% step %}
Review what happens
{% endstep %}
{% step %}
Confirm cancellation
{% endstep %}
{% endstepper %}
After cancellation:
* Access continues until period end
* Data is retained temporarily
* You can resubscribe later
## Reactivating
{% stepper %}
{% step %}
Log in to Kaana
{% endstep %}
{% step %}
You'll see reactivation prompt
{% endstep %}
{% step %}
Choose a plan
{% endstep %}
{% step %}
Enter payment info
{% endstep %}
{% step %}
Access is restored
{% endstep %}
{% endstepper %}
## Billing Contact
{% stepper %}
{% step %}
Go to Billing
{% endstep %}
{% step %}
Click **Billing Contact**
{% endstep %}
{% step %}
Enter email address
{% endstep %}
{% step %}
Save
{% endstep %}
{% endstepper %}
Update who receives billing emails.
## Billing Issues
### Failed Payment
{% stepper %}
{% step %}
You'll receive notification
{% endstep %}
{% step %}
Update payment method
{% endstep %}
{% step %}
Retry payment
{% endstep %}
{% endstepper %}
## Questions
Billing questions and next steps
* Check payment history
* Review your plan details
* Contact support if needed
***
Related Articles
* [Subscription Plans](/product/billing-and-plans/subscription-plans)
* [Program Planner](/product/planning-and-resources/program-planner)
* [Roles & Permissions](broken://pages/7a3664d23450c042d7e7084f78947259f6049fcc)
* [Payment Methods](/product/billing-and-plans/payment-methods)
* [Managed Services](/product/managed-services/managed-services-overview)
# Payment Methods
Manage how you pay for your Kaana subscription.
Updated over a month ago
## Supported Payment Methods
* Credit cards (Visa, Mastercard, American Express)
* Debit cards
* Some regions support additional methods
## Managing Payment Methods
### Access Payment Settings
{% stepper %}
{% step %}
Go to **Settings** > **Billing**
{% endstep %}
{% step %}
Click **Payment Methods**
{% endstep %}
{% endstepper %}
### View Current Method
See your active payment method:
* Card type and last 4 digits
* Expiration date
* Billing address
## Adding a Payment Method
### Add a Card
{% stepper %}
{% step %}
Click **Add Payment Method**
{% endstep %}
{% step %}
Enter card details:
* Card number
* Expiration date
* CVV
* Billing name
* Billing address
{% endstep %}
{% step %}
Click **Add Card**
{% endstep %}
{% endstepper %}
### Set as Default
If you have multiple methods:
{% stepper %}
{% step %}
Find the method to use
{% endstep %}
{% step %}
Click **Set as Default**
{% endstep %}
{% step %}
This card will be charged
{% endstep %}
{% endstepper %}
## Updating Payment Methods
### Update Card Details
When your card expires or changes:
{% stepper %}
{% step %}
Click **Edit** on the payment method
{% endstep %}
{% step %}
Update the details
{% endstep %}
{% step %}
Save changes
{% endstep %}
{% endstepper %}
### Update Billing Address
{% stepper %}
{% step %}
Click **Edit** on the payment method
{% endstep %}
{% step %}
Update address fields
{% endstep %}
{% step %}
Save changes
{% endstep %}
{% endstepper %}
## Removing Payment Methods
### Delete a Card
{% stepper %}
{% step %}
Find the card to remove
{% endstep %}
{% step %}
Click **Remove**
{% endstep %}
{% step %}
Confirm deletion
{% endstep %}
{% endstepper %}
Note: You can't remove your only payment method if you have an active subscription.
## Payment Security
### Your Data is Safe
* Card numbers are never stored directly
* Payments processed by Stripe
* PCI-compliant security
* Encrypted transactions
### What We Store
* Last 4 digits of card
* Card type
* Expiration date
* Billing address
We never store:
* Full card numbers
* CVV codes
## Failed Payments
### Why Payments Fail
Common reasons:
* Card expired
* Insufficient funds
* Bank declined
* Card number changed
### When Payment Fails
{% stepper %}
{% step %}
We'll email you
{% endstep %}
{% step %}
We'll retry automatically
{% endstep %}
{% step %}
Update your payment method
{% endstep %}
{% step %}
Service continues during grace period
{% endstep %}
{% endstepper %}
### Resolving Failed Payments
{% stepper %}
{% step %}
Check the error message
{% endstep %}
{% step %}
Verify card details are correct
{% endstep %}
{% step %}
Contact your bank if needed
{% endstep %}
{% step %}
Update or add a new payment method
{% endstep %}
{% step %}
Retry the payment
{% endstep %}
{% endstepper %}
## Receipts and Invoices
### Automatic Receipts
After each payment:
* Email receipt sent
* Invoice available in billing history
### Download Invoices
{% stepper %}
{% step %}
Go to **Billing**
{% endstep %}
{% step %}
Click **Payment History**
{% endstep %}
{% step %}
Find the invoice
{% endstep %}
{% step %}
Click **Download PDF**
{% endstep %}
{% endstepper %}
### Invoice Details
Invoices include:
* Your company details
* Itemized charges
* Payment method used
* Transaction ID
## Currency
### Billing Currency
* Prices shown in your billing currency
* Set during initial subscription
* Contact support to change
### Multi-Currency
Some plans support:
* Pricing in local currency
* Invoices in local currency
***
Related Articles
* [Authentication Security](broken://pages/21175a7ea265f0daeed32d4678b8ee03f06004e9)
* [Security Settings](broken://pages/5fed5afeb7826c4e601ba1a9dd3401a48eee73f7)
* [Frequently Asked Questions](broken://pages/9b2e5ca1bab9e9395374273776cdf152fa16da30)
* [Managing Your Subscription](/product/billing-and-plans/managing-your-subscription)
* [Managed Services](/product/managed-services/managed-services-overview)
Did this answer your question?
😞 😐 😃
# AI & Integrations
Kaana brings AI-driven execution and deep integrations together to help RevOps teams operate faster, with more confidence, across their revenue stack. This section covers how Kaana connects systems, applies intelligence, and supports execution at scale.
You'll see some of the best parts of GitBook in action — and find help on how you can turn this template into your own.
### Explore the topics below
| | | | |
|---|
| Getting Started | Set up Kaana AI and integrations for your RevOps environment | | | AI & Integrations |
| Kaana AI (Kai) | Understand how Kai supports analysis, guidance, and execution | | | Kaana AI (Kai) |
| AI Resolution | Resolve issues and questions using AI-assisted workflows | | | AI Resolution |
| Kai Toolbox | Explore AI-powered tools for RevOps execution and analysis | | | Kai Toolbox |
| Health Assessment | Evaluate system health across your revenue stack | | | Health Assessment |
| Integrations | Connect Kaana with Salesforce, Zuora, Stripe, and more | | | Integrations |
# AI Security
How Kaana protects your data when using AI features.
Updated over a month ago
## Overview
Kaana's AI features (Kai Advisor, Health Assessments, Contract to Subscription AI) are designed with privacy and security as top priorities.
## How AI Features Work
{% stepper %}
{% step %}
When you use an AI feature, relevant data is sent to our AI provider.
{% endstep %}
{% step %}
The AI processes the request.
{% endstep %}
{% step %}
Results are returned to you.
{% endstep %}
{% step %}
Your data is not stored by the AI provider.
{% endstep %}
{% endstepper %}
## Data Sent to AI
### What IS Sent
Only data necessary for the specific request:
| Feature | Data Sent |
| ------------------------------- | ---------------------------------------------- |
| **Kai Advisor** | Project summary, task counts, milestone status |
| **Health Assessment** | Aggregated metrics, not individual records |
| **Contract to Subscription AI** | Document content you choose to analyze |
### What is NOT Sent
* Passwords or authentication tokens
* Payment information
* Personal identification numbers
* Data from other users or tenants
## AI Provider Security
We use OpenAI as our AI provider. Their security commitments:
* No Training on Your Data — Your data is not used to train AI models
* Data Retention — API data retained for 30 days max for abuse monitoring, then deleted
* Encryption — All data encrypted in transit and at rest
* SOC 2 Compliant — Enterprise-grade security standards
## Your Control Over AI
### Opt-In Features
AI features are optional. You choose when to:
* Run AI analysis on a project
* Use the AI advisor
* Analyze documents with AI
### No Automatic Processing
AI doesn't automatically scan your data. It only processes information when you explicitly request it.
### Audit Trail
All AI interactions are logged so you can see:
* When AI was used
* What was analyzed
* Results generated
## AI Output Accuracy
### Important Disclaimers
* AI insights are suggestions, not guarantees
* Always verify AI recommendations
* AI may occasionally produce inaccurate results
* Use AI as a tool, not a replacement for judgment
### Human Review
For critical decisions:
* Review AI suggestions carefully
* Verify against actual data
* Consult with team members
* Document decisions made
## Best Practices
{% stepper %}
{% step %}
Review before submitting — Check what data will be analyzed.
{% endstep %}
{% step %}
Sanitize sensitive content — Remove confidential info if needed.
{% endstep %}
{% step %}
Validate outputs — Don't blindly trust AI results.
{% endstep %}
{% step %}
Report issues — Let us know if something seems wrong.
{% endstep %}
{% endstepper %}
## Protecting Sensitive Information
* Avoid analyzing documents with highly sensitive data
* Redact confidential information before AI analysis
* Use AI for general insights, not sensitive details
## Frequently Asked Questions
Does AI have access to all my data?
No. AI only sees data you explicitly choose to analyze.
Is my data used to train AI models?
No. Your data is never used for AI training.
Can other users see my AI interactions?
No. AI interactions are private to your account and tenant.
What happens if AI gives wrong advice?
AI provides suggestions only. You maintain control over all decisions. Always verify important recommendations.
Can I disable AI features?
Yes. AI features are optional and can be avoided if preferred.
## Security Updates
We continuously monitor and update our AI security practices:
* Regular security reviews
* Provider compliance verification
* Prompt response to any concerns
# Kaana Advisor (KAI)
Kaana Advisor is your AI-powered assistant that provides insights and recommendations for your projects.
### What is Kaana Advisor?
Kaana Advisor (KAI) analyzes your project data to:
* Identify risks and concerns
* Suggest actions and improvements
* Provide health assessments
* Answer questions about your projects
### Accessing Kaana Advisor
### Project Insights
{% stepper %}
{% step %}
### Open a project
Open the project you want to review.
{% endstep %}
{% step %}
### Locate Advisor
Look for the **Advisor** or **AI Insights** section.
{% endstep %}
{% step %}
### View insights
View the generated insights.
{% endstep %}
{% endstepper %}
### Chat Interface
{% stepper %}
{% step %}
Click the **AI Assistant** icon.
{% endstep %}
{% step %}
Ask questions in natural language.
{% endstep %}
{% step %}
Get answers based on your data.
{% endstep %}
{% endstepper %}
### Types of Insights
### Risk Identification
KAI analyzes your project and identifies:
* Overdue tasks and milestones
* Resource conflicts
* Scope concerns
* Timeline risks
### Recommendations
Based on analysis, KAI suggests:
* Actions to mitigate risks
* Process improvements
* Priority adjustments
* Next steps
### Health Assessment
Get an overall health score for your project:
* Green: On track
* Yellow: Minor concerns
* Red: Needs attention
### Generating Insights
### Automatic Insights
KAI periodically analyzes projects and generates:
* Fresh insights
* Updated recommendations
* Status changes
### Manual Refresh
{% stepper %}
{% step %}
Open the project
{% endstep %}
{% step %}
Click **Refresh Insights**
{% endstep %}
{% step %}
Wait for analysis to complete
{% endstep %}
{% step %}
Review new insights
{% endstep %}
{% endstepper %}
### Interacting with Insights
### View Details
Click on an insight to see:
* Full explanation
* Related data
* Suggested actions
### Accept Recommendations
{% stepper %}
{% step %}
Review the recommendation
{% endstep %}
{% step %}
Click **Accept** to implement
{% endstep %}
{% step %}
Or dismiss if not applicable
{% endstep %}
{% endstepper %}
### Dismiss Insights
{% stepper %}
{% step %}
Click **Dismiss**
{% endstep %}
{% step %}
Optionally provide feedback
{% endstep %}
{% step %}
The insight is hidden
{% endstep %}
{% endstepper %}
### Chat with KAI
#### Asking Questions
Type questions in natural language, for example:
* "What are the top risks in this project?"
* "Which tasks are overdue?"
* "How is the project health trending?"
#### Getting Answers
KAI responds with:
* Data-backed answers
* Relevant context
* Suggested actions
#### Conversation History
Previous conversations are saved:
* Scroll to see history
* Reference past questions
* Continue conversations
### Best Practices
#### Keeping Data Current
* Update task statuses regularly
* Log activities and issues
* The more data KAI has, the better insights
#### Acting on Insights
* Review insights regularly
* Address high-priority recommendations
* Track which actions you take
#### Providing Feedback
* Mark insights as helpful or not
* This improves future recommendations
* Report inaccurate insights
### Permissions
Access to Kaana Advisor depends on your role:
* View insights: Most users
* Run analysis: Users with appropriate permissions
* Configure: Administrators
### Privacy
KAI only analyzes data within your organization:
* Data is tenant-isolated
* No data is shared between organizations
* Insights are private to your team
# Kai Resolution Agent
Kai is Kaana's AI-powered resolution agent that analyzes System Feed signals and helps fix issues directly in your connected billing and CRM systems.
### Overview
When you encounter a signal in the System Feed, Kai can analyze the underlying problem, identify root causes, and propose specific actions to resolve it. For automated actions, Kai can execute fixes directly in your connected systems.
### How Kai Thinks About Problems
Kai uses intelligent anomaly detection to focus on issues that truly matter to your business. Rather than flagging every small error, Kai identifies patterns that indicate systemic, abnormal, or high-risk behavior.
#### What Kai Looks For (Anomalies)
| Anomaly Type | Example |
| -------------------------- | --------------------------------------------- |
| **Failure rate spikes** | Payment failures jump from 2% to 20% |
| **Volume changes** | Invoice generation drops 50% overnight |
| **Multi-entity patterns** | Same error affecting multiple customers |
| **System inconsistencies** | Usage recorded but no charges created |
| **Post-change failures** | Billing errors starting after a config update |
#### What Kai Ignores (Not Anomalies)
* A single customer's card decline due to insufficient funds
* Isolated expired card errors
* One-off data entry mistakes
This approach ensures Kai helps you address root causes rather than chasing individual symptoms.
### Understanding Root Causes
Kai understands how billing systems work and fixes problems at the right level. Billing operations flow through a sequence:
```
Usage → Rating → Billing → Invoices → Payments
```
If a billing run fails, Kai knows that no invoices were created yet, so it will recommend retrying the billing run - not individual invoices. This prevents wasted effort on symptoms while the root cause remains.
For example:
* If **usage processing** fails, invoices can't be generated - Kai fixes the usage first
* If **credentials are invalid**, payments will fail - Kai recommends refreshing credentials before retrying payments
* If a **billing run** fails, affected invoices don't exist yet - Kai retries the billing run, not invoices
### Starting a Resolution Session
1. Navigate to the **System Feed**
2. Open any signal that requires action
3. Click **Resolve with Kai** to start an agent session
4. Kai will analyze the signal and present its findings
### The Resolution Process
#### Step 1: Analysis
Kai analyzes the signal and provides:
* **Root Cause** - What's actually causing the problem
* **Impact Assessment** - How this affects your business
* **Affected Systems** - Which integrations and entities are involved
* **Confidence Level** - How certain Kai is about the diagnosis
#### Step 2: Proposed Actions
Based on the analysis, Kai proposes specific actions to resolve the issue. Each action includes:
* **Description** - What the action does
* **Type** - Automated (Kai executes) or Manual (you execute)
* **Target System** - Which integration will be affected
* **Risk Level** - Low, Medium, or High
* **Expected Outcome** - What should happen after execution
* **Detailed Steps** - Specific operations that will be performed
#### Step 3: Confirmation
Review each proposed action before execution. You control what Kai does:
* Select which actions to approve
* Skip actions you want to handle manually
* Cancel the session if you prefer to address it differently
#### Step 4: Execution
For approved automated actions, Kai:
1. Connects to your integration
2. Executes the specific API calls
3. Records the system response
4. Reports success or failure with details
#### Step 5: Results
After execution, you see detailed results:
**Successful Actions:**
* Green checkmark with "Action Completed"
* System response data (invoice numbers, IDs, status, amounts)
* Confirmation of what changed
**Failed Actions:**
* Red X with "Action Failed"
* Error message explaining what went wrong
* Full API response for troubleshooting
### Understanding the Action Timeline
Kai presents actions in a visual timeline format:
| Stage | Color | Description |
| ------------------- | ------ | ------------------------------------ |
| **Issue** | Red | The problem being addressed |
| **Action** | Amber | The resolution action to take |
| **Steps** | Blue | Detailed steps involved |
| **API Call** | Purple | The specific system API being called |
| **Expected Result** | Green | What should happen after execution |
### Action Types
Actions are categorized by execution method:
#### Automated Actions
Kai can execute these directly in your connected systems:
* No manual intervention required
* Real-time execution with immediate feedback
* Full audit trail of changes made
#### Manual Actions
Some situations require your intervention:
* Actions that need human judgment
* Steps that must be performed in the external system's UI
* Escalations to support teams or customers
For manual actions, Kai provides detailed instructions on what to do.
### Available Resolution Actions
Kai can perform a variety of actions across your connected billing systems:
#### Integration Actions
| Action | Description |
| ----------------------- | -------------------------------------- |
| **Refresh Credentials** | Update API tokens or OAuth connections |
| **Verify Integration** | Test that the connection is working |
#### Usage & Rating Actions
| Action | Description |
| ------------------------- | ------------------------------- |
| **Reprocess Usage Batch** | Resubmit failed usage records |
| **Replay Usage Events** | Resend usage events for rating |
| **Recalculate Charges** | Recalculate pricing for charges |
#### Billing Run Actions
| Action | Description |
| ---------------------- | ------------------------------- |
| **Retry Billing Run** | Re-execute a failed billing run |
| **Cancel Billing Run** | Cancel a stuck billing run |
#### Invoice Actions
| Action | Description |
| --------------------- | --------------------------- |
| **Retry Invoice** | Regenerate a failed invoice |
| **Backfill Invoices** | Create missing invoices |
| **Void Invoice** | Cancel an erroneous invoice |
#### Payment Actions
| Action | Description |
| ----------------------- | ----------------------------------- |
| **Retry Payment** | Attempt payment collection again |
| **Retry Payment Batch** | Re-run a failed payment batch |
| **Pause Payment Runs** | Temporarily stop payment collection |
#### Subscription Actions
| Action | Description |
| --------------------------- | ------------------------------------- |
| **Sync Subscription State** | Align subscription status with source |
| **Repair Entitlements** | Fix entitlement mismatches |
#### Configuration Actions
| Action | Description |
| -------------------------- | ----------------------------------- |
| **Review Configuration** | Manual review of system settings |
| **Rollback Configuration** | Revert recent configuration changes |
#### Escalation Actions
| Action | Description |
| ----------------------- | ------------------------------- |
| **Escalate to Support** | Create a support ticket |
| **Contact Customer** | Reach out to affected customers |
Kai prioritizes actions based on root cause analysis. For example, if there's an authentication issue, Kai will recommend fixing credentials before trying to retry payments.
### Activity Tracking
All resolution activity is recorded in the signal's Activity section:
| Entry | Icon | Meaning |
| --------------------------- | ----------- | ------------------------------------------- |
| **AI Resolution Completed** | Green robot | All actions succeeded |
| **AI Resolution Failed** | Red robot | One or more actions failed |
| **Marked as In Progress** | Play icon | Agent session started |
| **Resolved** | Checkmark | Signal automatically resolved after success |
When all automated actions complete successfully, Kai automatically marks the signal as "Resolved."
### Permissions
Access to Kai Resolution requires specific permissions:
| Permission | What It Allows |
| ------------------------------ | --------------------------------------------- |
| **view\_agent\_remediation** | View resolution sessions and proposed actions |
| **update\_agent\_remediation** | Start sessions and approve/execute actions |
Administrators can configure these permissions through role management.
### Plan Requirements
* **Advanced Plan** - AI resolution requires the Advanced plan or higher
* The **agentAI** plan feature must be enabled
### Integration Requirements
For Kai to execute actions:
* **Active Integration** - The connected system must be active and healthy
* **Valid Credentials** - API credentials must be current and have write permissions
* **Sufficient Permissions** - The integration's API key must have permission for the specific operations
### Best Practices
#### Before Starting a Session
* Review the signal details and affected entities
* Ensure your integration credentials are valid
* Understand the potential business impact
#### During Confirmation
* Read each proposed action carefully
* Consider the risk level for high-impact actions
* Start with low-risk actions if you're uncertain
#### After Execution
* Review the results for each action
* Check the affected records in your source system
* Add comments to the signal documenting what was done
### Troubleshooting
#### "Session failed to start"
* Check that your integration is active
* Verify API credentials are still valid
* Ensure you have the required permissions
#### "Action execution failed"
* Review the error message for specific details
* Check if the entity still exists in the source system
* Verify the integration has write permissions
* Try the action manually in the source system
#### "No actions proposed"
* Kai may not have enough data to propose actions
* The issue may require manual investigation
* Check if the signal has sufficient context
### Data Privacy & Security
* Kai only accesses data necessary for analysis and execution
* All actions are logged in the audit trail
* Execution results are stored securely within your tenant
* Kai respects your integration's permission boundaries
# Understanding the Signal Initial Guess
When you view a signal in the System Feed, Kai provides an "Initial Guess" to help you quickly understand what went wrong.
### What is the Initial Guess?
The Initial Guess is Kai's first assessment of the root cause behind an issue. Instead of showing you generic messages like "1 payment has failed", Kai tries to show you the actual reason, such as "The access token you've used is not a valid sandbox API access token".
### How does it work?
Kai uses a smart approach to find the most helpful information:
#### Step 1: Look for specific error messages
Kai first checks the affected entities (the actual records that have issues) for meaningful error messages. For example, if a payment failed, the payment record often contains the exact reason from the payment gateway.
#### Step 2: Use AI analysis (when available)
If the system has AI capabilities enabled, Kai sends the signal data to an AI model that understands revenue operations. The AI provides a contextual analysis of what likely went wrong.
#### Step 3: Fall back to extracted details
If AI isn't available, Kai extracts key details from the error data and presents them in a readable format.
### Examples
| What you might have seen before | What Kai shows now |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| "1 payment has failed and needs investigation" | "The access token you've used is not a valid sandbox API access token" |
| "Invoice generation failed" | "Customer account missing required billing address" |
| "3 deals are at risk" | "Acme Corp deal ($50,000, closing Jan 25) needs immediate attention" |
### Why is this helpful?
* **Faster troubleshooting**: You immediately know what to fix
* **Less clicking**: No need to dig into each affected entity
* **Actionable insights**: The real error message tells you exactly what went wrong
### Find Root Cause button
If you need more detailed analysis, click the "Find Root Cause" button. This launches a deeper AI investigation that examines all the related data and provides comprehensive recommendations.
# Contract to Subscription
Contract to Subscription uses AI to analyze contract documents and generate billing subscriptions.
### What is Contract to Subscription?
Contract to Subscription helps you:
* Analyze contract documents
* Extract key information
* Identify important clauses
* Compare contract versions
### Accessing Contract to Subscription
Navigate to **Contract to Subscription** from the main menu (if enabled for your organization).
### Uploading Contracts
#### Upload a Document
1. Go to **Contract to Subscription**
2. Click **Upload Contract**
3. Select your file:
* PDF documents
* Word documents (.docx)
4. Wait for processing
#### Processing Time
Analysis may take a moment depending on:
* Document size
* Complexity
* Current system load
### Analyzing Contracts
#### View Analysis
After upload, see:
* Document summary
* Key terms identified
* Important dates
* Parties involved
* Notable clauses
#### Key Information Extracted
Contract to Subscription identifies:
* **Parties** - Who is involved
* **Dates** - Start, end, renewal dates
* **Values** - Contract amounts and terms
* **Obligations** - What each party must do
* **Termination** - How the contract can end
* **Special Clauses** - Non-compete, confidentiality, etc.
### Working with Results
#### Review Findings
1. Examine each identified section
2. Verify accuracy
3. Note any items of concern
#### Export Analysis
Save the analysis for reference:
1. Click **Export**
2. Choose format (PDF, document)
3. Download the summary
#### Link to Projects
Associate contracts with projects:
1. View the analyzed contract
2. Click **Link to Project**
3. Select the relevant project
4. The contract appears in project documents
### Best Practices
#### Document Quality
* Upload clear, readable documents
* Avoid scanned documents with poor quality
* Use original digital documents when possible
#### Verification
* Always verify AI-extracted information
* Check critical terms manually
* Don't rely solely on AI analysis for legal decisions
#### Organization
* Name contracts clearly
* Link to relevant projects
* Keep analysis for reference
### Limitations
Contract to Subscription is a tool to assist, not replace legal review:
* Results should be verified by qualified personnel
* Complex contracts may need professional review
* AI may miss nuanced language
### Permissions
Access to Contract to Subscription requires:
* Appropriate role permissions
* Feature to be enabled for your organization
* Document access permissions
# Health Assessments Overview
Health Assessments provide an AI-powered analysis of your project and organizational health.
## What are Health Assessments?
Health Assessments automatically analyze your data to:
* Identify risks and concerns
* Measure key metrics
* Compare against benchmarks
* Provide recommendations
* Generate an overall health score
## Assessment Domains
Health Assessments cover multiple areas:
### Projects
* Task completion rates
* Overdue tasks and milestones
* Issue trends
* Activity levels
### Managed Services
* Service request status
* Response times
* Integration health
### Integrations
* Connection status
* Sync performance
* Error rates
### Contracts
* Expiration dates
* Compliance status
* Key terms monitoring
## Running an Assessment
### Manual Assessment
{% stepper %}
{% step %}
### Navigate to Health Assessments
Open the Health Assessments section in the product.
{% endstep %}
{% step %}
### Select the scope
Choose one of the following:
* Entire organization
* Specific project
* Specific area
{% endstep %}
{% step %}
### Run Assessment
Click **Run Assessment** and wait for the analysis to complete.
{% endstep %}
{% endstepper %}
### Scheduled Assessments
* Assessments can run automatically: daily, weekly, or monthly
* Results delivered via notification
* Historical tracking enabled
## Understanding Results
### Health Score
Overall health is displayed as:
* **Green (Good)** — On track, healthy metrics
* **Yellow (Warning)** — Minor concerns, monitor closely
* **Red (Critical)** — Needs immediate attention
### Findings
Each finding includes:
* **Status** — Pass, warn, or fail
* **Impact** — How this affects your organization
* **Summary** — Brief description
* **Details** — Full explanation
* **Evidence** — Supporting data
### Metrics
Key metrics measured:
* Task completion rate
* Issue resolution time
* Activity frequency
* Document count
* Milestone achievement rate
## Reviewing Evidence
{% stepper %}
{% step %}
### Open a finding
Click on a finding to view more details.
{% endstep %}
{% step %}
### View Evidence
In the finding, open the **Evidence** section to see the actual data that triggered the finding, such as:
* Overdue tasks
* Open issues
* Missing milestones
{% endstep %}
{% step %}
### Inspect individual items
Click items in the evidence list to view their details.
{% endstep %}
{% endstepper %}
## Recommendations
Based on findings, you receive actionable recommendations:
* **Quick Fixes** — Immediate actions
* **Process Improvements** — Longer-term changes
* **Playbook Steps** — Guided procedures
* **AI Suggestions** — Proposed actions
## Acting on Recommendations
{% stepper %}
{% step %}
### Review the recommendation
Assess if the recommendation applies to your context.
{% endstep %}
{% step %}
### Accept or Dismiss
* Click **Accept** to implement
* Or **Dismiss** if not applicable
{% endstep %}
{% step %}
### Track progress
Monitor which recommendations were addressed and their outcomes.
{% endstep %}
{% endstepper %}
## Assessment History
{% stepper %}
{% step %}
### Open History
Go to **Health Assessments** and click **History**.
{% endstep %}
{% step %}
### Review past runs
See previous assessments with details such as:
* Date and time
* Who triggered it
* Overall score
* Key findings
{% endstep %}
{% step %}
### Compare scores
Use history to compare scores over time.
{% endstep %}
{% endstepper %}
## Health Controls
Assessments are based on configurable controls:
| Control | What it Checks |
| ---------------- | ------------------------------- |
| Task Health | Overdue tasks, completion rates |
| Milestone Health | Upcoming/overdue milestones |
| Issue Health | Open issues, resolution time |
| Activity Health | Recent activity levels |
| Document Health | Documentation completeness |
## Permissions
Access to Health Assessments requires the following permissions:
* View: See assessment results
* Run: Trigger new assessments
* Export: Download reports
* Configure: Modify controls
## Best Practices
### Regular Assessments
* Run weekly assessments minimum
* Review results promptly
* Act on critical findings
### Track Trends
* Compare scores over time
* Identify improving/declining areas
* Celebrate improvements
### Use Evidence
* Drill into the data
* Understand root causes
* Make data-driven decisions
### Follow Recommendations
* Prioritize high-impact items
* Track implementation
* Measure improvement
# Integrations Overview
Connect Kaana to other tools and services your organization uses.
## Available Integrations
Kaana can integrate with various services:
### Communication
* **Slack** — Send notifications to Slack channels
### Time Tracking
* **Harvest** — Sync time entries with projects
### CRM
* **Salesforce** — Connect customer data
* HubSpot — Connect customer data
### Billing
* **Zuora** — Subscription management
* **Stripe** — Subscription management
### Other
* Custom webhook integrations
***
{% stepper %}
{% step %}
### Accessing Integrations
* Go to **Settings**
* Select **Integrations**
* View connected and available integrations
{% endstep %}
{% step %}
### Connecting Integrations — OAuth Integrations
For services like Slack or Salesforce:
* Find the integration
* Click **Connect**
* Log in to the service
* Authorize Kaana
* Configuration completes
{% endstep %}
{% step %}
### Connecting Integrations — API Key Integrations
For services requiring API keys:
* Find the integration
* Click **Configure**
* Enter your API key
* Click **Save**
{% endstep %}
{% step %}
### Connecting Integrations — Webhook Integrations
For custom webhooks:
* Go to **Integrations**
* Click **Add Webhook**
* Enter:
* Webhook URL
* Events to trigger
* Secret (optional)
* Click **Save**
{% endstep %}
{% endstepper %}
***
## Managing Integrations
{% stepper %}
{% step %}
#### View Connection Status
Each integration shows:
* Connected or disconnected
* Last sync time
* Error status (if any)
{% endstep %}
{% step %}
#### Refresh Connection
If an integration has issues:
* Open the integration
* Click **Refresh**
* Re-authenticate if needed
{% endstep %}
{% step %}
#### Disconnect Integration
* Open the integration
* Click **Disconnect**
* Confirm
Data previously synced remains in Kaana.
{% endstep %}
{% endstepper %}
***
## Harvest Integration
{% stepper %}
{% step %}
#### Connect Harvest
* Find Harvest in integrations
* Click **Connect**
* Log in to Harvest
* Authorize access
{% endstep %}
{% step %}
#### Link Projects
Map Harvest projects to Kaana projects:
* Open a project
* Click **Link Harvest Project**
* Select the Harvest project
Time entries sync automatically.
{% endstep %}
{% step %}
#### View Time Data
See Harvest time in:
* Project overview
* Task details
* Reports
{% endstep %}
{% endstepper %}
***
## Slack Integration
{% stepper %}
{% step %}
#### Connect Slack
* Find Slack in integrations
* Click **Connect**
* Select your workspace
* Choose a channel
* Authorize
{% endstep %}
{% step %}
#### Configure Notifications
Choose what to send to Slack:
* Task assignments
* Project updates
* Issue alerts
* Milestone achievements
{% endstep %}
{% endstepper %}
***
## Webhook Integration
{% stepper %}
{% step %}
#### Create a Webhook
* Click **Add Webhook**
* Enter the endpoint URL
* Select events:
* Project created
* Task updated
* Issue created
* etc.
* Add authentication if required
* Save
{% endstep %}
{% step %}
#### Test Webhook
* Open the webhook
* Click **Test**
* Check that your endpoint received data
{% endstep %}
{% step %}
#### View Webhook Logs
See recent webhook calls:
* Success/failure status
* Response codes
* Retry attempts
{% endstep %}
{% endstepper %}
***
## Troubleshooting
Connection Failed
* Check your credentials
* Verify the service is accessible
* Try disconnecting and reconnecting
Sync Not Working
* Check integration status
* Look for error messages
* Verify permissions in the connected service
Missing Data
* Confirm the data was created after connecting
* Check filter settings
* Verify project/entity links
Permissions
Managing integrations requires:
* Admin or Owner role
* Integration management permission
# Operational Guides for Revenue, Billing, and Automation Teams
Practical, field-tested guides for teams running Zuora, Salesforce, and modern RevOps stacks.
These guides are written for operators, architects, and RevOps leaders who care about accuracy, resilience, and scale — not theory.
Inside, you’ll find step-by-step frameworks, detection rules, and decision guides based on real production systems, real failures, and real recovery scenarios.
If you’re responsible for billing accuracy, subscription workflows, or revenue integrity, you’re in the right place.
### Who These Guides Are For
* RevOps leaders responsible for revenue accuracy
* Billing and Zuora administrators
* Solution architects and technical consultants
* Finance and systems teams supporting subscription businesses
If you operate in high-volume, high-complexity subscription environments, these guides were written for you.
### What You’ll Find Here
| | | | | |
|---|
| Feature Guides | Deep dives into specific capabilities and patterns — from AI-assisted monitoring to workflow recovery strategies. | | | Feature Guides | |
| RevOps Guides | Clear frameworks to help you make tradeoff-heavy decisions across CPQ, billing, and revenue operations. | | | RevOps Guides | |
| Detection Rule Guides | Concrete, production-ready detection patterns you can adapt to your own environment. | | | Detection Rule Guides | |
# Guide: AI-Assisted Zuora Workflow Monitoring & Recovery
### Feature Overview
Zuora workflows are powerful—but when they fail, stall, or partially execute, the impact often goes unnoticed until downstream systems break, revenue is delayed, or finance is forced into manual cleanup.
**AI‑Assisted Zuora Workflow Monitoring & Recovery** gives teams real‑time visibility into workflow health, proactively detects failures and anomalies, and guides recovery before issues escalate.
This feature is designed for teams that rely on Zuora as a mission‑critical billing engine and want confidence that workflows are running as intended—without constantly babysitting them.
***
### Who This Is For
* Billing Operations teams managing complex workflows
* RevOps and Finance Ops teams dependent on accurate billing events
* Technical admins responsible for Zuora stability
* Organizations using Zuora Workflows at scale
***
### Business Value
* **Reduce silent failures** that lead to billing delays or revenue leakage
* **Cut manual troubleshooting time** by surfacing root causes immediately
* **Improve operational confidence** in automated billing processes
* **Enable proactive issue resolution** instead of reactive fire drills
Teams using this feature spend less time diagnosing problems and more time improving workflows.
***
### Key Capabilities
* Continuous monitoring of Zuora workflow executions
* AI‑driven detection of failures, stalls, and anomalous behavior
* Intelligent alerting based on severity and business impact
* Guided recovery recommendations for failed workflows
* Execution history and audit trail for operational review
***
### How It Works (High‑Level)
1. Kaana continuously listens to workflow execution events in Zuora
2. AI models analyze execution patterns, failures, and deviations
3. Issues are categorized by type and impact
4. Alerts and insights are surfaced in the Kaana dashboard
5. Users are guided through recovery actions or escalation paths
***
### Step‑by‑Step Usage
#### 1. View Workflow Health Dashboard
* Navigate to **Zuora → Workflow Monitoring** in Kaana
* Review overall workflow status (Healthy, At Risk, Failed)
* Identify workflows requiring attention
#### 2. Inspect a Workflow Issue
* Select a flagged workflow execution
* Review detected failure type (e.g., API error, data mismatch, timeout)
* See contextual details and related execution history
#### 3. Follow Recovery Guidance
* Review Kaana’s recommended recovery actions
* Re‑run workflows or apply corrective steps as needed
* Confirm successful execution
#### 4. Track Resolution
* Workflow status updates automatically
* Resolution is logged for audit and reporting
***
### Common Use Cases
#### Workflow Failures After Zuora Configuration Changes
Catch and resolve failures caused by field changes, product updates, or API modifications before they impact billing.
#### High‑Volume Billing Periods
Maintain confidence during renewals, amendments, and invoicing cycles when workflow load is highest.
#### Managed Services Oversight
Enable Kaana teams to proactively monitor and support customer environments without constant manual checks.
***
### Permissions & Roles
* **Admins**: Configure monitoring and recovery actions
* **Operators**: View issues and follow recovery guidance
* **View‑Only Users**: Access dashboards and execution history
***
### Guardrails & Considerations
* Requires active Zuora Workflow usage
* Monitoring accuracy improves with historical execution data
* Recovery actions respect existing Zuora permissions and controls
***
### Success Metrics
* Reduction in undetected workflow failures
* Faster mean time to resolution (MTTR)
* Fewer billing delays caused by automation issues
* Improved confidence in automated billing operations
***
### Summary
AI‑Assisted Zuora Workflow Monitoring & Recovery transforms workflow management from reactive troubleshooting into proactive operational assurance—giving teams clarity, control, and confidence in their billing automation.
# Guide: CPQ vs No-CPQ: A RevOps Decision Framework
### Purpose of This Guide
Choosing whether to implement CPQ (Configure, Price, Quote) is one of the most consequential RevOps decisions a company will make. Done well, CPQ can enable scale. Done poorly—or too early—it can slow sales, frustrate teams, and introduce long-term operational debt.
This guide provides a RevOps-first framework to help you decide if, when, and how CPQ fits into your revenue stack.
***
### What CPQ Is (and What It Isn’t)
#### What CPQ Is
CPQ is a system designed to:
* Standardize product configuration
* Enforce pricing and discount rules
* Generate accurate quotes at scale
* Reduce manual errors in complex deals
#### What CPQ Is Not
CPQ is not:
* A silver bullet for messy sales processes
* A substitute for poor product or pricing strategy
* A shortcut to RevOps maturity
* Necessary for every B2B business
From a RevOps perspective, CPQ is an amplifier. It magnifies what already exists—good or bad.
***
### The Core RevOps Question
> “Are we solving complexity—or creating it?”
RevOps should recommend CPQ only when operational complexity exceeds what disciplined process and lightweight automation can handle.
***
### When You Do Not Need CPQ
Many companies reach for CPQ prematurely. You likely do not need CPQ if most of the following are true:
#### Sales Motion
* Deals are relatively simple and repeatable
* SKUs are limited and stable
* Minimal bundling or configuration
* Sales reps can quote accurately with guardrails
#### Pricing & Contracts
* Pricing is straightforward (flat, tiered, or simple usage)
* Discounts are rare or tightly controlled
* Contract terms don’t vary wildly
#### Volume & Scale
* Low-to-moderate deal volume
* Sales team is small or highly experienced
* Manual review does not bottleneck bookings
#### RevOps Reality Check
If RevOps is spending more time maintaining CPQ logic than enabling sales, CPQ is likely premature.
***
### When CPQ Does Make Sense
CPQ becomes valuable when complexity is real, repeatable, and revenue-impacting.
#### Strong CPQ Indicators
You should seriously evaluate CPQ if you have:
* Complex product configurations (modules, dependencies, exclusions)
* Frequent custom bundles or add-ons
* Multi-year, ramped, or usage-based pricing
* High quote volume with recurring errors
* Heavy reliance on deal desk or RevOps approvals
* Sales reps spending meaningful time building quotes
#### RevOps Signal
When RevOps becomes a human CPQ system, it’s time to automate.
***
### CPQ vs No-CPQ: A Decision Matrix
| Product Complexity | Low–Moderate | Moderate–High |
| --------------------- | ------------ | ------------------------- |
| Pricing Variability | Minimal | High |
| Sales Velocity | Moderate | High-volume or enterprise |
| Error Tolerance | High | Low |
| RevOps Overhead | Low | Medium–High |
| Change Frequency | High | Stable |
| Implementation Cost | Low | High |
| Long-Term Flexibility | High | Medium |
{% hint style="info" %}
Key Insight: CPQ trades flexibility for control. RevOps must decide which matters more at the current stage.
{% endhint %}
***
### The Hidden Costs of CPQ (RevOps Perspective)
CPQ introduces costs that are rarely accounted for upfront:
#### Operational Costs
* Ongoing rule maintenance
* Product and pricing changes become slower
* Increased dependency on admins or consultants
#### Organizational Costs
* Sales resistance if UX is poor
* Shadow quoting outside CPQ
* RevOps becomes gatekeeper instead of enabler
#### Technical Costs
* Tight coupling to CRM and billing
* Fragile logic across Salesforce, Zuora, and downstream systems
* High effort to unwind later
RevOps should plan for CPQ as a long-term commitment, not a feature toggle.
***
### The “No-CPQ, But Disciplined” Alternative
Many high-performing RevOps teams delay CPQ successfully by combining:
* Clear product catalog design
* Strong Salesforce validation rules
* Controlled discounting workflows
* Template-based quoting
* Zuora-native configuration where appropriate
* Lightweight automation instead of heavy logic
\
This approach preserves flexibility while building institutional discipline.
***
### RevOps Readiness Checklist for CPQ
Before implementing CPQ, RevOps should confidently answer “yes” to most of the following:
* Our product catalog is stable and well-defined
* Pricing strategy is documented and enforced
* Sales process is consistent across teams
* RevOps owns quote-to-cash governance
* Salesforce data quality is high
* Downstream systems (billing, finance) are aligned
* Leadership understands the tradeoffs
If not, CPQ will surface—not solve—these gaps.
***
### How CPQ Fits into Salesforce + Zuora Environments
In subscription businesses, CPQ decisions must consider:
* Where configuration logic should live
* Avoiding duplicated rules across systems
* Managing amendments, renewals, and expansions
* Aligning quotes with billing reality
In many cases, lighter Salesforce quoting paired with Zuora-native billing logic is more sustainable than full CPQ.
***
### Kaana’s Point of View
At Kaana, we approach CPQ as a last-mile optimization, not a foundation.
Our philosophy:
* Start with process clarity
* Automate only proven patterns
* Avoid locking clients into rigid systems too early
* Design RevOps stacks that scale *and* adapt
Sometimes CPQ is the right answer. Often, it’s not—yet.
***
### Final Takeaway
CPQ is not a maturity badge. It’s a tradeoff.
The best RevOps teams:
* Delay CPQ until complexity demands it
* Implement it with intention
* Design for change, not perfection
If you’re unsure whether CPQ is helping or hurting your RevOps motion, that uncertainty itself is a signal worth exploring.
# Guide: Building Your Own Detection Rules
This section walks you through creating custom detection rules. Use the system rules above as templates and reference examples.
#### The Five Building Blocks
Every detection rule has five components that work together:
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ SOURCE │ → │ FILTER │ → │ AGGREGATE │ → │ EVALUATE │ → │ FINGERPRINT │
│ │ │ │ │ │ │ │ │ │
│ What data │ │ Which │ │ How to │ │ When to │ │ How to │
│ to query │ │ records │ │ summarize │ │ trigger │ │ identify │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```
***
#### Step 1: Choose Your Data Source
The source tells the rule what type of data to query from your connected system.
**Available Sources by Integration:**
| Integration | Available Objects |
| -------------- | ------------------------------------------------------------------- |
| **Zuora** | account, subscription, invoice, payment, billrun, creditmemo, usage |
| **Stripe** | customer, invoice, payment\_intent, subscription, refund, dispute |
| **Salesforce** | Account, Opportunity, Lead, Contact, Case |
**Example from System Rules:**
* *Failed Bill Run Detection* uses `billrun` from Zuora
* *Dispute Rate Signal* uses `dispute` from Stripe
* *Stale Opportunity Pipeline* uses `Opportunity` from Salesforce
***
#### Step 2: Add Filters
Filters narrow down which records to examine. You can combine multiple filters.
**Available Operators:**
| Operator | Meaning | Example |
| -------- | --------------------- | ------------------------------------------ |
| `=` | Equals | Status equals "Error" |
| `!=` | Not equals | Status is not "Active" |
| `>` | Greater than | Amount greater than 1000 |
| `>=` | Greater than or equal | Balance at least 0 |
| `<` | Less than | Count less than 5 |
| `<=` | Less than or equal | Age at most 30 days |
| `in` | Matches any in list | Status is "Error", "Failed", or "Canceled" |
| `not_in` | Doesn't match any | Stage is not "Closed Won" or "Closed Lost" |
**Examples from System Rules:**
| Rule | Filter Logic |
| --------------------------- | --------------------------------------------------------------------------------- |
| Failed Bill Run Detection | Status **in** \["Error", "Failed", "Canceled"] |
| Outstanding Account Balance | Balance **>** 0 **AND** Status **=** "Active" |
| High-Value Deal at Risk | Amount **>** 100,000 **AND** IsClosed **=** false |
| Stale Opportunity Pipeline | IsClosed **=** false **AND** StageName **not\_in** \["Closed Won", "Closed Lost"] |
**Tip:** Use multiple filters to be precise. The *Outstanding Account Balance* rule uses two filters to find only active accounts with a positive balance—this avoids false signals from closed accounts.
***
#### Step 3: Configure Aggregation
Aggregation determines how the rule summarizes the filtered data.
**Aggregation Functions:**
| Function | What It Does | Use When |
| -------- | ---------------------------- | ------------------------------------------------------ |
| `count` | Counts the number of records | You care about **how many** (e.g., failed payments) |
| `sum` | Adds up a numeric field | You care about **total amount** (e.g., refund dollars) |
**Time Windows:**
| Window | Duration | Best For |
| ------------- | -------- | ----------------------- |
| 60 minutes | 1 hour | Detecting sudden spikes |
| 360 minutes | 6 hours | Short-term patterns |
| 1440 minutes | 24 hours | Daily monitoring |
| 10080 minutes | 7 days | Weekly trends |
**Grouping Options:**
| Approach | Result | Use When |
| -------------------- | ------------------------------- | --------------------------------------------------- |
| No grouping | One total for all records | You want overall volume (e.g., total refund amount) |
| Group by account | Separate count/sum per account | You want per-customer signals |
| Group by owner | Separate count/sum per owner | You want per-rep signals |
| Group by status/type | Separate count/sum per category | You want to see patterns by type |
**Examples from System Rules:**
| Rule | Function | Window | Grouped By |
| ----------------------- | ------------ | -------- | ------------------- |
| Failed Payment Spike | count | 1 hour | Payment method type |
| Credit Memo Spike | sum (amount) | 24 hours | Not grouped |
| Subscription Churn Risk | count | 7 days | Account |
| Lead Response Time SLA | count | 24 hours | Lead owner |
**Tip:** The *Failed Payment Spike* rule uses a short 1-hour window and groups by payment method type—this helps you spot if a specific payment processor is having issues.
***
#### Step 4: Set the Evaluation Threshold
The threshold determines when the rule creates a signal.
**Available Comparisons:**
| Operator | Meaning | Example |
| ------------- | --------------------- | ------------ |
| `>` or `gt` | Greater than | More than 10 |
| `>=` or `gte` | Greater than or equal | 1 or more |
| `<` or `lt` | Less than | Fewer than 5 |
| `<=` or `lte` | Less than or equal | 100 or fewer |
| `=` or `eq` | Equals | Exactly 0 |
**Choosing the Right Threshold:**
| Scenario | Recommended Threshold |
| ---------------------------- | --------------------------------------------------- |
| Any occurrence is a problem | >= 1 (e.g., failed bill runs) |
| Small numbers are normal | > 5 or > 10 (e.g., payment declines) |
| Large volumes are concerning | > 10,000 (e.g., usage spikes) |
| Dollar amounts | Set based on your business (e.g., > $5,000 refunds) |
**Examples from System Rules:**
| Rule | Threshold | Reasoning |
| ------------------------- | --------------- | ------------------------------------------------- |
| Failed Bill Run Detection | >= 1 | Any failed bill run needs attention |
| Failed Payment Spike | > 10 per hour | A few failures are normal; 10+ suggests a problem |
| High Invoice Aging | > 5 per account | Multiple aged invoices indicate collection issues |
| Large Refund Volume | > $5,000/day | High refund volume may signal problems |
**Tip:** Start with a higher threshold to reduce noise, then lower it as you understand your normal patterns.
***
#### Step 5: Configure Fingerprinting
Fingerprinting controls how signals are grouped and deduplicated.
**Fingerprint Modes:**
| Mode | Behavior | Use When |
| ----------- | ---------------------------------- | -------------------------------------------------------------- |
| `entity` | One signal per unique record | You want to track individual items (e.g., each failed payment) |
| `aggregate` | One signal for the overall pattern | You want to track volume trends (e.g., daily refund total) |
**Examples from System Rules:**
| Rule | Mode | Fields | Result |
| ----------------------- | --------- | ---------------------- | --------------------------------------- |
| Failed Payment Signal | entity | Account ID, Payment ID | One signal per failed payment |
| Credit Memo Spike | aggregate | (none) | One signal when daily total is high |
| Subscription Churn Risk | entity | Account ID | One signal per at-risk account |
| Failed Payment Spike | aggregate | Payment method type | One signal per payment type with issues |
**Tip:** Use `entity` mode when each individual record needs attention. Use `aggregate` mode when you care about overall patterns rather than individual items.
***
#### Putting It All Together: A Custom Rule Example
Let's say you want to detect **Zuora accounts with failed payments in the last week that have a balance over $500**.
**Step 1 - Source:** Zuora accounts
**Step 2 - Filters:**
* Balance > 500
* Status = "Active"
**Step 3 - Aggregation:**
* Function: count
* Window: 7 days (10080 minutes)
* Group by: Account ID
**Step 4 - Evaluation:**
* Threshold: >= 1 (any matching account)
**Step 5 - Fingerprint:**
* Mode: entity
* Fields: Account ID
**Result:** You'll get one signal for each active account with a balance over $500, and the signals won't duplicate for the same account within the week.
***
#### Quick Reference: Common Rule Patterns
**Pattern 1: Catch Every Occurrence**
{% code overflow="wrap" lineNumbers="true" %}
```
Use when: Each individual issue needs attention
Filter: Specific error condition
Aggregate: count, no grouping
Threshold: >= 1
Fingerprint: entity mode with record ID
Example: Failed Bill Run Detection
```
{% endcode %}
**Pattern 2: Detect Volume Spikes**
{% code overflow="wrap" lineNumbers="true" %}
```
Use when: High volume indicates a systemic issue
Filter: Broad or no filter
Aggregate: count or sum, short time window (1-6 hours)
Threshold: High number based on your normal volume
Fingerprint: aggregate mode
Example: Failed Payment Spike, Credit Memo Spike
```
{% endcode %}
**Pattern 3: Per-Customer Monitoring**
{% code overflow="wrap" lineNumbers="true" %}
```
Use when: You want signals grouped by customer/account
Filter: Problem condition
Aggregate: count, group by account/customer ID
Threshold: >= 1 or based on acceptable count
Fingerprint: entity mode with account ID
Example: Outstanding Account Balance, Failed Subscription Payment
```
{% endcode %}
**Pattern 4: Team Performance Tracking**
{% code overflow="wrap" lineNumbers="true" %}
```
Use when: Monitoring by owner/rep
Filter: Condition indicating issues
Aggregate: count, group by owner ID
Threshold: Based on acceptable workload
Fingerprint: entity mode with owner ID
Example: Lead Response Time SLA, Stale Opportunity Pipeline
```
{% endcode %}
***
### Rule Categories Explained
| Category | What It Covers |
| -------------------- | --------------------------------------------------- |
| **Payment Health** | Payment processing, failures, gateway issues |
| **Billing Accuracy** | Invoice generation, bill runs, pricing errors |
| **Revenue Leakage** | Unbilled usage, missed charges, lost revenue |
| **Churn Risk** | Cancellations, at-risk customers, retention signals |
| **Pipeline Health** | Sales opportunity progress and stale deals |
| **Sales Efficiency** | Lead response times and sales process metrics |
| **Revenue Risk** | High-value deals at risk of loss |
| **Data Integrity** | Data quality, sync issues, missing records |
***
### Severity Levels
| Level | When to Use | Response Time |
| ------------ | ------------------------------------------ | ------------------- |
| **Critical** | Immediate revenue or customer impact | Same day |
| **Warning** | Potential issue that needs attention | Within a few days |
| **Info** | Awareness item, no immediate action needed | Review periodically |
***
### Best Practices
1. **Start with Critical Rules** - Activate the critical severity rules first as they catch the most urgent issues
2. **Link to Production Integrations** - Connect rules to your production systems, not test environments
3. **Monitor the System Feed** - Check your feed regularly for new signals from detection rules
4. **Document Your Responses** - Use the signal notes feature to track what actions you've taken
5. **Review Rule Performance** - Periodically check if rules are generating useful signals or need adjustment
# Billing Accuracy Rules
# Rule: Failed Bill Run Detection (Zuora)
**Category:** Billing Accuracy\
**Severity:** Critical\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Bill runs in your Zuora account that have failed, errored, or been canceled.
**How It Works:**
| Setting | Value |
| ------------- | --------------------------------------------------- |
| Data Source | Zuora Bill Runs |
| Looks For | Bill runs with status of Error, Failed, or Canceled |
| Time Window | Last 24 hours |
| Triggers When | 1 or more matching bill runs found |
| Groups By | Each individual bill run |
**Why It Matters:**\
Failed bill runs can prevent invoices from being generated, which delays billing and impacts cash flow. Catching these quickly ensures your billing cycle stays on track.
**Recommended Actions:**
* Review the bill run error details in Zuora
* Check for data issues in the affected accounts
* Fix any underlying problems and re-run the billing
* Contact Zuora support if the issue persists
# Rule: Credit Memo Spike (Zuora)
**Category:** Billing Accuracy\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Unusual spikes in credit memos.
**How It Works:**
| Setting | Value |
| ------------- | ---------------------------------------- |
| Data Source | Zuora Credit Memos |
| Looks For | All credit memos |
| Time Window | Last 24 hours |
| Triggers When | Total credit memo amount exceeds $10,000 |
| Groups By | Overall total (not grouped) |
**Why It Matters:**\
High credit memo volume may indicate billing errors or policy abuse.
**Recommended Actions:**
* Review credit memo reasons
* Audit billing accuracy
* Check for duplicate credits
# Rule: Usage-Based Billing Anomaly (Zuora)
**Category:** Billing Accuracy\
**Severity:** Info\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Unusual usage patterns that may indicate billing issues.
**How It Works:**
| Setting | Value |
| ------------- | ----------------------------------------------------- |
| Data Source | Zuora Usage Records |
| Looks For | All usage records |
| Time Window | Last 24 hours |
| Triggers When | Total usage quantity exceeds 10,000 units per account |
| Groups By | Account |
**Why It Matters:**\
Anomalous usage could indicate data issues or customer behavior changes that need attention.
**Recommended Actions:**
* Verify usage data accuracy
* Check for duplicate records
* Contact customer for validation
# Churn Risk Rules
# Rule: Cancelled Subscription Signal (Zuora)
**Category:** Churn Risk\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Subscriptions that have been recently cancelled in Zuora.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Zuora Subscriptions |
| Looks For | Subscriptions with status of Cancelled |
| Time Window | Last 24 hours |
| Triggers When | 1 or more cancelled subscriptions |
| Groups By | Subscription and associated account |
**Why It Matters:**\
Tracking cancellations helps you understand churn patterns and enables proactive retention efforts. Early intervention can sometimes save at-risk customers.
**Recommended Actions:**
* Review the cancellation reason
* Reach out to understand customer concerns
* Offer incentives or solutions if appropriate
* Update your retention playbook based on patterns
# Rule: Subscription Churn Risk (Zuora)
**Category:** Churn Risk\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Accounts with multiple cancelled subscriptions indicating high churn risk.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Zuora Subscriptions |
| Looks For | Subscriptions with status of Cancelled |
| Time Window | Last 7 days |
| Triggers When | 2 or more cancelled subscriptions per account |
| Groups By | Account |
**Why It Matters:**\
Identifying at-risk accounts enables proactive intervention to retain customers.
**Recommended Actions:**
* Trigger customer success outreach
* Offer retention incentives
* Schedule health check call
# Rule: Failed Subscription Payment (Stripe)
**Category:** Churn Risk\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Stripe
**What It Monitors:**\
Recurring subscription payments that have failed.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Stripe Invoices |
| Looks For | Open invoices with more than 1 payment attempt |
| Time Window | Last 24 hours |
| Triggers When | 1 or more failed subscription invoices per customer |
| Groups By | Customer |
**Why It Matters:**\
Failed subscription payments lead to involuntary churn if not addressed.
**Recommended Actions:**
* Send payment update request
* Retry with updated payment method
* Offer payment plan if needed
# Rule: Account Health Score Drop (Salesforce)
**Category:** Churn Risk\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System**: Salesforce
**What It Monitors:**\
Accounts with declining engagement or satisfaction scores.
**How It Works:**
| Setting | Value |
| ------------- | -------------------------------------- |
| Data Source | Salesforce Accounts |
| Looks For | Accounts with type of "Customer" |
| Time Window | Last 7 days |
| Triggers When | More than 3 at-risk accounts per owner |
| Groups By | Account owner |
**Why It Matters:**\
Declining health scores often precede churn.
**Recommended Actions:**
* Schedule customer health check
* Review support ticket history
* Prepare retention offer
# Data Integrity Rules
# Rule: Revenue Sync Discrepancy (Zuora)
**Category:** Data Integrity\
**Severity:** Critical\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Discrepancies between CRM and billing system revenue figures.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Zuora Invoices |
| Looks For | Invoices with status of Posted or Paid |
| Time Window | Last 24 hours |
| Triggers When | Total invoice amount exceeds $1,000,000 |
| Groups By | Overall total (not grouped) |
**Why It Matters:**\
Revenue mismatches can cause reporting errors and compliance issues.
**Recommended Actions:**
* Run reconciliation report
* Identify missing sync records
* Trigger manual data sync
# Payment Health Rules
# Rule: Failed Payment Signal (Zuora)
**Category:** Payment Health\
**Severity:** Critical\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Individual payments that have failed or errored in Zuora.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Zuora Payments |
| Looks For | Payments with status of Error |
| Time Window | Last 24 hours |
| Triggers When | 1 or more failed payments per account |
| Groups By | Account and individual payment |
**Why It Matters:**\
Failed payments mean lost revenue and can lead to customer churn if not addressed quickly. Proactive follow-up can recover revenue and improve customer relationships.
**Recommended Actions:**
* Contact the customer to update their payment method
* Retry the payment once details are updated
* Offer alternative payment options if needed
* Send dunning notifications as appropriate
\
# Rule: Failed Payment Spike (Zuora)
**Category:** Payment Health\
**Severity:** Critical\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Sudden increases in payment failure rates compared to normal levels.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Zuora Payments |
| Looks For | Payments with status of Error |
| Time Window | Last 1 hour |
| Triggers When | More than 10 failed payments |
| Groups By | Payment method type (credit card, ACH, etc.) |
**Why It Matters:**\
A spike in payment failures could indicate a payment gateway issue, fraud attack, or widespread payment method expiration. Quick response can minimize revenue impact.
**Recommended Actions:**
* Check payment gateway status
* Review error codes for patterns
* Contact your payment processor if needed
# Rule: Dispute Rate Signal (Stripe)
**Category:** Payment Health\
**Severity:** Critical\
**Run Frequency:** Every 60 minutes
**Target System:** Stripe
**What It Monitors:**\
Dispute and chargeback rates approaching risky thresholds.
**How It Works:**
| Setting | Value |
|---|
| Data Source | Stripe Disputes |
| Looks For | Disputes with status of "needs_response" or "under_review" |
| Time Window | Last 7 days |
| Triggers When | More than 5 active disputes |
| Groups By | Overall total (not grouped) |
**Why It Matters:**\
High dispute rates can affect your Stripe account standing and result in penalties.
**Recommended Actions:**
* Review dispute reasons
* Gather evidence for response
* Improve checkout fraud detection
# Rule: Payment Method Decline Rate (Stripe)
**Category:** Payment Health\
**Severity:** Info\
**Run Frequency:** Every 60 minutes
**Target System:** Stripe
**What It Monitors:**\
High decline rates on payment methods.
**How It Works:**
| Setting | Value |
| ------------- | --------------------------------------------------------------------- |
| Data Source | Stripe Payment Intents |
| Looks For | Payment intents with status of "requires\_payment\_method" (declined) |
| Time Window | Last 6 hours |
| Triggers When | More than 20 declined payments per payment method type |
| Groups By | Payment method type (card, bank transfer, etc.) |
**Why It Matters:**\
Elevated decline rates could indicate card network issues.
**Recommended Actions:**
* Check card network status
* Review decline codes
* Consider alternative payment methods
# Pipeline Health Rules
# Rule: Stale Opportunity Pipeline (Salesforce)
**Category:** Pipeline Health\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Salesforce
**What It Monitors:**\
Opportunities stuck in the same stage for too long.
**How It Works:**
| Setting | Value |
| ------------- | -------------------------------------------------------------- |
| Data Source | Salesforce Opportunities |
| Looks For | Open opportunities not in "Closed Won" or "Closed Lost" stages |
| Time Window | Last 7 days |
| Triggers When | 3 or more stale opportunities per owner |
| Groups By | Opportunity owner and stage |
**Why It Matters:**\
Stale deals need sales attention to move forward or be properly closed.
**Recommended Actions:**
* Review opportunity blockers
* Schedule deal review meeting
* Update or close stale opportunities
# Revenue Leakage Rules
# Rule: Outstanding Account Balance (Zuora)
**Category:** Revenue Leakage\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Active accounts in Zuora that have outstanding (unpaid) balances.
**How It Works:**
| Setting | Value |
| ------------- | ---------------------------------------------- |
| Data Source | Zuora Accounts |
| Looks For | Active accounts with a balance greater than $0 |
| Time Window | Last 24 hours |
| Triggers When | 1 or more accounts with outstanding balance |
| Groups By | Each individual account |
**Why It Matters:**\
Outstanding balances represent revenue at risk. Long-term unpaid balances can become bad debt and affect your cash flow.
**Recommended Actions:**
* Review the account's payment history
* Send a balance reminder to the customer
* Check for payment method issues
* Escalate to collections if the balance is overdue
# Rule: High Invoice Aging (Zuora)
**Category:** Revenue Leakage\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Zuora
**What It Monitors:**\
Invoices that have been outstanding for too long.
**How It Works:**
| Setting | Value |
| ------------- | ------------------------------------------------------ |
| Data Source | Zuora Invoices |
| Looks For | Posted invoices with remaining balance greater than $0 |
| Time Window | Last 24 hours |
| Triggers When | More than 5 unpaid invoices per account |
| Groups By | Account |
**Why It Matters:**\
Aged invoices risk becoming bad debt and directly impact cash flow.
**Recommended Actions:**
* Review collection strategy
* Send payment reminders
* Escalate to collections team
# Rule: Large Refund Volume (Stripe)
**Category:** Revenue Leakage\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Stripe
**What It Monitors:**\
Unusually high refund amounts.
**How It Works:**
| Setting | Value |
| ------------- | ------------------------------------------------------ |
| Data Source | Stripe Refunds |
| Looks For | All refunds |
| Time Window | Last 24 hours |
| Triggers When | Total refund amount exceeds $5,000 (in cents: 500,000) |
| Groups By | Overall total (not grouped) |
**Why It Matters:**\
High refund volume may indicate product/service issues or policy abuse.
**Recommended Actions:**
* Analyze refund reasons
* Review product quality
* Update refund policy if needed
# Revenue Risk Rules
# Rule: High-Value Deal at Risk (Salesforce)
**Category:** Revenue Risk\
**Severity:** Critical\
**Run Frequency:** Every 60 minutes
**Target System:** Salesforce
**What It Monitors:**\
High-value opportunities with close dates approaching but no recent activity.
**How It Works:**
| Setting | Value |
| ------------- | ---------------------------------------------------- |
| Data Source | Salesforce Opportunities |
| Looks For | Open opportunities with amount greater than $100,000 |
| Time Window | Last 7 days |
| Triggers When | 1 or more high-value deals at risk |
| Groups By | Opportunity (with name and owner) |
**Why It Matters:**\
Large deals at risk represent significant potential revenue loss.
**Recommended Actions:**
* Escalate to sales leadership
* Schedule executive sponsor call
* Review competitive positioning
# Sales Efficiency Rules
# Rule: Lead Response Time SLA (Salesforce)
**Category:** Sales Efficiency\
**Severity:** Warning\
**Run Frequency:** Every 60 minutes
**Target System:** Salesforce
**What It Monitors:**\
Lead response times for SLA compliance.
**How It Works:**
| Setting | Value |
| ------------- | ------------------------------------------- |
| Data Source | Salesforce Leads |
| Looks For | New leads that have not been converted |
| Time Window | Last 24 hours |
| Triggers When | More than 5 uncontacted new leads per owner |
| Groups By | Lead owner |
**Why It Matters:**\
Slow lead response reduces conversion rates and wastes marketing investment.
**Recommended Actions:**
* Prioritize lead follow-up
* Redistribute leads if overloaded
* Review lead routing rules
# Developer Docs
Learn more about documenting APIs in GitBook.
Kaana provides developer resources that allow you to programmatically interact with the platform, integrate RevOps data, and automate workflows using our APIs.
Our OpenAPI specifications are currently being finalized and will be published here shortly, including endpoint documentation, authentication details, and request and response examples.
This section will serve as the central reference for building, extending, and integrating with the Kaana platform.
# API Overview
The Kaana API allows you to integrate Kaana with other systems and build custom workflows.
## What is the API?
The API (Application Programming Interface) lets you:
* Access your Kaana data programmatically
* Create custom integrations
* Automate workflows
* Build custom dashboards
* Sync data with other systems
## Who Should Use the API?
The API is designed for:
* Developers building integrations
* Technical teams automating workflows
* Partners building on Kaana
* Power users with technical skills
## What You Can Do
### Read Data
Retrieve information from Kaana:
* List projects and their details
* Get task information
* Fetch contacts and organizations
* Access documents metadata
* Read activities and issues
### Create Data
Add new records to Kaana:
* Create projects
* Add tasks
* Create contacts
* Log activities
* Upload documents
### Update Data
Modify existing records:
* Update project details
* Change task status
* Edit contact information
* Modify issue priority
### Delete Data
Remove records (with appropriate permissions):
* Delete projects
* Remove tasks
* Delete contacts
## Getting Started
{% stepper %}
{% step %}
### Get API Access
First, you need API credentials:
* Go to **Settings** > **API Keys**
* Create a new API key
* Save the key securely
{% endstep %}
{% step %}
### Authenticate
Include your API key in requests:
* Use Bearer token authentication
* Include it in the Authorization header
{% endstep %}
{% step %}
### Make Requests
Call API endpoints:
* Use HTTPS for all requests
* Send JSON data
* Receive JSON responses
{% endstep %}
{% endstepper %}
## Base URL
All API requests use this base URL:
```
https://app.kaana.com/api
```
For sandbox/development:
```
https://sandbox.kaana.com/api
```
## Request Format
### HTTP Methods
| Method | Purpose |
| ------ | -------------------- |
| GET | Retrieve data |
| POST | Create new data |
| PATCH | Update existing data |
| DELETE | Remove data |
### Headers
Required headers for all requests:
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```
### Request Body
For POST and PATCH requests, send JSON:
```json
{
"title": "New Project",
"description": "Project description"
}
```
## Response Format
### Success Response
```json
{
"data": {
"id": 123,
"title": "New Project"
}
}
```
### Error Response
```json
{
"error": "ValidationError",
"message": "Title is required"
}
```
## Rate Limits
API requests are rate limited:
* 100 requests per minute (standard)
* 1000 requests per minute (enterprise)
If you exceed limits:
* You'll receive a 429 status code
* Wait and retry after the reset period
## API Versioning
The current API version is included in responses. Backward compatibility is maintained and deprecations are announced in advance.
# API Authentication
Learn how to authenticate your API requests.
## Authentication Methods
### API Keys
The primary method for API authentication:
* Generate keys in Settings
* Include in request headers
* Keys are tied to your account
* Full access based on your permissions
### JWT Tokens
For web applications and OAuth flows:
* Obtained through Auth0 login
* Short-lived access tokens
* Include in Authorization header
## Using API Keys
### Getting an API Key
{% stepper %}
{% step %}
Go to **Settings** > **API Keys**
{% endstep %}
{% step %}
Click **Create API Key**
{% endstep %}
{% step %}
Name your key (e.g., "Integration Key")
{% endstep %}
{% step %}
Copy the key immediately
{% endstep %}
{% step %}
Store it securely
{% endstep %}
{% endstepper %}
Important: The key is only shown once. If you lose it, create a new one.
### Including the Key in Requests
Add the key to the Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```
### Example Request
```
curl -X GET "https://app.kaana.com/api/projects" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
```
## JWT Token Authentication
### Obtaining a Token
{% stepper %}
{% step %}
Redirect user to Auth0 login
{% endstep %}
{% step %}
User authenticates
{% endstep %}
{% step %}
Receive access token
{% endstep %}
{% step %}
Use token in requests
{% endstep %}
{% endstepper %}
### Using the Token
Include the JWT in requests:
```
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```
### Token Expiration
* Check `exp` claim for expiration
* Refresh tokens before expiry
* Re-authenticate if expired
## Security Best Practices
### Protect Your Keys
* Never share API keys
* Don't commit keys to code repositories
* Use environment variables
* Rotate keys periodically
### Use HTTPS
Always use HTTPS for API requests:
* Encrypts data in transit
* Protects your credentials
* Required for all endpoints
### Least Privilege
* Create keys with minimum needed access
* Use separate keys for different integrations
* Revoke unused keys
### Monitor Usage
* Review API key activity
* Check for unusual patterns
* Investigate unexpected usage
## Permissions
API access respects your account permissions:
* You can only access what you can access in the UI
* Tenant isolation is enforced
* Admin endpoints require admin role
## Error Responses
401 Unauthorized
```
{
"error": "Unauthorized",
"message": "Invalid or missing authentication token"
}
```
Solutions:
* Check that you included the Authorization header
* Verify your API key is correct
* Ensure the key hasn't been revoked
403 Forbidden
```
You don't have permission for this action:
{
"error": "Forbidden",
"message": "You don't have permission to access this resource"
}
```
Solutions:
* Verify you have the required role
* Check resource belongs to your tenant
* Contact admin for access
## Revoking Keys
If a key is compromised:
{% stepper %}
{% step %}
Go to **Settings** > **API Keys**
{% endstep %}
{% step %}
Find the compromised key
{% endstep %}
{% step %}
Click **Revoke**
{% endstep %}
{% step %}
Create a new key
{% endstep %}
{% step %}
Update your integrations
{% endstep %}
{% endstepper %}
## Testing Authentication
### Verify Your Key Works
```
curl -X GET "https://app.kaana.com/api/user" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Expected response:
```
{
"id": 123,
"username": "you@example.com",
"role": "admin"
}
```
## Common Issues
"Invalid token" error
* Check for typos in the key
* Ensure no extra spaces
* Verify key hasn't been revoked
"Token expired" error
* For JWT: obtain a new token
# API Keys
Learn how to create and manage API keys for programmatic access.
### What are API Keys?
API keys are credentials that allow you to:
* Access the Kaana API programmatically
* Build custom integrations
* Automate workflows
* Connect third-party tools
### Accessing API Key Settings
{% stepper %}
{% step %}
Go to **Settings** and select **API Keys**.
Note: Requires appropriate permissions.
{% endstep %}
{% endstepper %}
### Creating an API Key
#### Generate a New Key
{% stepper %}
{% step %}
Click **+ Create API Key**.
{% endstep %}
{% step %}
Enter a name for the key (e.g., "Zapier Integration").
{% endstep %}
{% step %}
Click **Create**.
{% endstep %}
{% step %}
Copy the key immediately — it's only shown once!
{% endstep %}
{% endstepper %}
#### Key Naming
Use descriptive names:
* Include the purpose: "Slack Integration"
* Include environment: "Dev Testing Key"
* Include owner if shared: "John's Dashboard Key"
### Viewing Your Keys
Your API keys list shows:
* Key name
* Created date
* Last used date
* Status (active/revoked)
You cannot view the full key after creation.
### Using Your API Key
#### In API Requests
Include the key in the Authorization header:
```
Authorization: Bearer YOUR_API_KEY
```
#### Example with cURL
```bash
curl -X GET "https://app.kaana.com/api/projects" \
-H "Authorization: Bearer abc123def456..." \
-H "Content-Type: application/json"
```
#### Example with JavaScript
```javascript
fetch('https://app.kaana.com/api/projects', {
headers: {
'Authorization': 'Bearer abc123def456...',
'Content-Type': 'application/json'
}
})
```
#### Example with Python
```python
import requests
headers = {
'Authorization': 'Bearer abc123def456...',
'Content-Type': 'application/json'
}
response = requests.get('https://app.kaana.com/api/projects', headers=headers)
```
### Revoking Keys
If a key is compromised or no longer needed:
{% stepper %}
{% step %}
Go to **Settings** > **API Keys**.
{% endstep %}
{% step %}
Find the key.
{% endstep %}
{% step %}
Click **Revoke**.
{% endstep %}
{% step %}
Confirm revocation.
Revoked keys immediately stop working. This cannot be undone.
{% endstep %}
{% endstepper %}
### Security Best Practices
#### Keep Keys Secret
* Never share keys publicly
* Don't put keys in source code
* Use environment variables
* Don't email keys
#### Store Securely
Good practices:
* Use a secrets manager
* Use environment variables
* Encrypt at rest
Bad practices:
* Storing in plain text files
* Committing to git repositories
* Sharing via unsecured channels
#### Rotate Keys
{% stepper %}
{% step %}
Create a new key.
{% endstep %}
{% step %}
Update your integrations.
{% endstep %}
{% step %}
Revoke the old key.
{% endstep %}
{% endstepper %}
#### Least Privilege
* Create separate keys for different uses
* Revoke keys you no longer need
* Audit key usage regularly
#### Key Permissions
API keys inherit your account permissions:
* If you're an admin, the key has admin access
* Tenant isolation is enforced
* You can only access your organization's data
### Troubleshooting
"Invalid API Key" Error
* Verify the key is correct (no extra spaces)
* Check if the key was revoked
* Ensure you're using Bearer authentication
"Unauthorized" Error
* Verify you have permission for the action
* Check if your account is active
* Confirm you're accessing the correct tenant
Key Not Working
Create a test request to /api/user.If it works, the issue is with the specific endpoint.If it fails, the key may be revoked or invalid.
### Limits
#### Number of Keys
You can create multiple API keys:
* Standard: Up to 5 active keys
* Enterprise: Unlimited keys
#### Rate Limits
API keys share your account's rate limits:
* 100 requests/minute (standard)
* Higher limits for enterprise
### Best Practices Summary
{% stepper %}
{% step %}
Name keys descriptively — Know what each key is for.
{% endstep %}
{% step %}
Store securely — Use environment variables or secrets managers.
{% endstep %}
{% step %}
Rotate regularly — Replace keys periodically.
{% endstep %}
{% step %}
Revoke when done — Remove unused keys.
{% endstep %}
{% step %}
Monitor usage — Watch for unusual activity.
{% endstep %}
{% step %}
Use separate keys — One per integration.
{% endstep %}
{% endstepper %}
# Projects
# Projects
Project management operations
## List all projects
> Returns a list of projects accessible to the authenticated user.\
> \- Admins and consultants see all projects within their organization\
> \- Regular users see only projects they own
```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ProjectWithTags":{"allOf":[{"$ref":"#/components/schemas/Project"},{"type":"object","properties":{"owner_username":{"type":"string","description":"Username of the project owner"},"tags":{"type":"array","description":"Tags associated with the project","items":{"type":"object","properties":{"tagId":{"type":"integer"},"tag":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"isGlobal":{"type":"boolean"},"categoryId":{"type":"integer","nullable":true}}}}}}}}]},"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects":{"get":{"tags":["Projects"],"summary":"List all projects","description":"Returns a list of projects accessible to the authenticated user.\n- Admins and consultants see all projects within their organization\n- Regular users see only projects they own\n","operationId":"listProjects","responses":{"200":{"description":"List of projects","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectWithTags"}}}}},"401":{"description":"Not authenticated","content":{"text/plain":{"schema":{"type":"string"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create a new project
> Creates a new project within the authenticated user's organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ProjectCreate":{"type":"object","required":["title","description","status"],"properties":{"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Initial project status"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID to base the project on"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID to associate"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date (ISO 8601 format)"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date (ISO 8601 format)"},"metadata":{"type":"object","nullable":true,"description":"Additional metadata"}}},"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects":{"post":{"tags":["Projects"],"summary":"Create a new project","description":"Creates a new project within the authenticated user's organization","operationId":"createProject","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreate"}}}},"responses":{"200":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Validation error","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Delete a project
> Deletes a project. Only project owners or users with delete\_projects permission can delete.\
> Projects with related items (tasks, documents, activities) cannot be deleted until those items are removed.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects/{id}":{"delete":{"tags":["Projects"],"summary":"Delete a project","description":"Deletes a project. Only project owners or users with delete_projects permission can delete.\nProjects with related items (tasks, documents, activities) cannot be deleted until those items are removed.\n","operationId":"deleteProject","parameters":[{"name":"id","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Project deleted successfully"},"400":{"description":"Cannot delete project with related items","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Server error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Update a project
> Updates an existing project. Only project owners or users with edit\_projects permission can update.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ProjectUpdate":{"type":"object","properties":{"title":{"type":"string","description":"Updated project title"},"description":{"type":"string","description":"Updated project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Updated project status"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Updated start date (ISO 8601 format or empty string to clear)"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Updated due date (ISO 8601 format or empty string to clear)"},"templateId":{"type":"string","nullable":true},"playbookId":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}}},"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"ErrorResponse":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/projects/{id}":{"patch":{"tags":["Projects"],"summary":"Update a project","description":"Updates an existing project. Only project owners or users with edit_projects permission can update.","operationId":"updateProject","parameters":[{"name":"id","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUpdate"}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid date format or validation error","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project not found","content":{"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Server error","content":{"text/plain":{"schema":{"type":"string"}}}}}}}}}
```
## Duplicate a project
> Creates a copy of an existing project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Projects API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Project management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Project":{"type":"object","required":["id","title","description","status","ownerId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique project identifier"},"title":{"type":"string","description":"Project title"},"description":{"type":"string","description":"Project description"},"status":{"type":"string","enum":["active","completed","on_hold"],"description":"Current project status"},"ownerId":{"type":"integer","description":"User ID of the project owner"},"templateId":{"type":"string","nullable":true,"description":"Optional template ID the project was created from"},"playbookId":{"type":"string","nullable":true,"description":"Optional playbook ID associated with the project"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Project start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Project due date"},"metadata":{"type":"object","nullable":true,"description":"Additional project metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/projects/{id}/duplicate":{"post":{"tags":["Projects"],"summary":"Duplicate a project","description":"Creates a copy of an existing project","operationId":"duplicateProject","parameters":[{"name":"id","in":"path","required":true,"description":"Project ID to duplicate","schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"New title for the duplicated project"}}}}}},"responses":{"200":{"description":"Project duplicated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}}}}
```
# Activities
Activity management operations
## List all activities
> Returns all activities accessible to the authenticated user within their organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ActivityWithRelations":{"allOf":[{"$ref":"#/components/schemas/Activity"},{"type":"object","properties":{"creator":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string","nullable":true}}},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}]},"Activity":{"type":"object","required":["id","timestamp","type","description","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique activity identifier"},"timestamp":{"type":"string","format":"date-time","description":"When the activity occurred"},"type":{"type":"string","enum":["note","email","phone_call","meeting","document","task","service","slack"],"description":"Activity type"},"subtype":{"type":"string","nullable":true,"description":"Activity subtype for categorization"},"description":{"type":"string","description":"Activity description/content"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"creatorId":{"type":"integer","description":"User ID who created the activity"},"metadata":{"type":"object","nullable":true,"description":"Additional activity metadata"},"evidence":{"type":"object","nullable":true,"description":"Supporting evidence/attachments"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/activities":{"get":{"tags":["Activities"],"summary":"List all activities","description":"Returns all activities accessible to the authenticated user within their organization","operationId":"listActivities","responses":{"200":{"description":"List of activities","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActivityWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Create a new activity
> Creates a new activity (note, email, phone call, meeting, etc.)
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ActivityCreate":{"type":"object","required":["timestamp","type","description"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"When the activity occurred (ISO 8601 format)"},"type":{"type":"string","enum":["note","email","phone_call","meeting","document","task","service","slack"]},"subtype":{"type":"string","nullable":true},"description":{"type":"string","description":"Activity description/content"},"projectId":{"type":"integer","nullable":true,"description":"Project to associate with"},"organizationId":{"type":"integer","nullable":true,"description":"Organization to associate with"},"metadata":{"type":"object","nullable":true},"evidence":{"type":"object","nullable":true}}},"Activity":{"type":"object","required":["id","timestamp","type","description","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique activity identifier"},"timestamp":{"type":"string","format":"date-time","description":"When the activity occurred"},"type":{"type":"string","enum":["note","email","phone_call","meeting","document","task","service","slack"],"description":"Activity type"},"subtype":{"type":"string","nullable":true,"description":"Activity subtype for categorization"},"description":{"type":"string","description":"Activity description/content"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"creatorId":{"type":"integer","description":"User ID who created the activity"},"metadata":{"type":"object","nullable":true,"description":"Additional activity metadata"},"evidence":{"type":"object","nullable":true,"description":"Supporting evidence/attachments"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/activities":{"post":{"tags":["Activities"],"summary":"Create a new activity","description":"Creates a new activity (note, email, phone call, meeting, etc.)","operationId":"createActivity","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityCreate"}}}},"responses":{"200":{"description":"Activity created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Activity"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Project or organization not found"},"500":{"description":"Server error"}}}}}}
```
## Get an activity
> Returns a specific activity by ID
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ActivityWithRelations":{"allOf":[{"$ref":"#/components/schemas/Activity"},{"type":"object","properties":{"creator":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string","nullable":true}}},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}]},"Activity":{"type":"object","required":["id","timestamp","type","description","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique activity identifier"},"timestamp":{"type":"string","format":"date-time","description":"When the activity occurred"},"type":{"type":"string","enum":["note","email","phone_call","meeting","document","task","service","slack"],"description":"Activity type"},"subtype":{"type":"string","nullable":true,"description":"Activity subtype for categorization"},"description":{"type":"string","description":"Activity description/content"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"creatorId":{"type":"integer","description":"User ID who created the activity"},"metadata":{"type":"object","nullable":true,"description":"Additional activity metadata"},"evidence":{"type":"object","nullable":true,"description":"Supporting evidence/attachments"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/activities/{id}":{"get":{"tags":["Activities"],"summary":"Get an activity","description":"Returns a specific activity by ID","operationId":"getActivity","parameters":[{"name":"id","in":"path","required":true,"description":"Activity ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Activity details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityWithRelations"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Activity not found"},"500":{"description":"Server error"}}}}}}
```
## List activities for a project
> Returns all activities associated with a specific project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ActivityWithRelations":{"allOf":[{"$ref":"#/components/schemas/Activity"},{"type":"object","properties":{"creator":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string","nullable":true}}},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}]},"Activity":{"type":"object","required":["id","timestamp","type","description","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique activity identifier"},"timestamp":{"type":"string","format":"date-time","description":"When the activity occurred"},"type":{"type":"string","enum":["note","email","phone_call","meeting","document","task","service","slack"],"description":"Activity type"},"subtype":{"type":"string","nullable":true,"description":"Activity subtype for categorization"},"description":{"type":"string","description":"Activity description/content"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"creatorId":{"type":"integer","description":"User ID who created the activity"},"metadata":{"type":"object","nullable":true,"description":"Additional activity metadata"},"evidence":{"type":"object","nullable":true,"description":"Supporting evidence/attachments"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/projects/{projectId}/activities":{"get":{"tags":["Activities"],"summary":"List activities for a project","description":"Returns all activities associated with a specific project","operationId":"listProjectActivities","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of project activities","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActivityWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## List activities for an organization
> Returns all activities associated with a specific organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ActivityWithRelations":{"allOf":[{"$ref":"#/components/schemas/Activity"},{"type":"object","properties":{"creator":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string","nullable":true}}},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}]},"Activity":{"type":"object","required":["id","timestamp","type","description","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique activity identifier"},"timestamp":{"type":"string","format":"date-time","description":"When the activity occurred"},"type":{"type":"string","enum":["note","email","phone_call","meeting","document","task","service","slack"],"description":"Activity type"},"subtype":{"type":"string","nullable":true,"description":"Activity subtype for categorization"},"description":{"type":"string","description":"Activity description/content"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"creatorId":{"type":"integer","description":"User ID who created the activity"},"metadata":{"type":"object","nullable":true,"description":"Additional activity metadata"},"evidence":{"type":"object","nullable":true,"description":"Supporting evidence/attachments"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/organizations/{organizationId}/activities":{"get":{"tags":["Activities"],"summary":"List activities for an organization","description":"Returns all activities associated with a specific organization","operationId":"listOrganizationActivities","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of organization activities","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ActivityWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## List comments on an activity
> Returns all comments for a specific activity
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Comment":{"type":"object","required":["id","content","userId","createdAt","updatedAt"],"properties":{"id":{"type":"integer"},"content":{"type":"string"},"activityId":{"type":"integer","nullable":true},"userId":{"type":"integer"},"parentId":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}}}}}},"paths":{"/activities/{activityId}/comments":{"get":{"tags":["Activities"],"summary":"List comments on an activity","description":"Returns all comments for a specific activity","operationId":"listActivityComments","parameters":[{"name":"activityId","in":"path","required":true,"description":"Activity ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of comments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
## Add a comment to an activity
> Creates a new comment on an activity
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Comment":{"type":"object","required":["id","content","userId","createdAt","updatedAt"],"properties":{"id":{"type":"integer"},"content":{"type":"string"},"activityId":{"type":"integer","nullable":true},"userId":{"type":"integer"},"parentId":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}}}}}},"paths":{"/activities/{activityId}/comments":{"post":{"tags":["Activities"],"summary":"Add a comment to an activity","description":"Creates a new comment on an activity","operationId":"createActivityComment","parameters":[{"name":"activityId","in":"path","required":true,"description":"Activity ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Comment content"},"parentId":{"type":"integer","nullable":true,"description":"Parent comment ID for replies"}}}}}},"responses":{"200":{"description":"Comment created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Add a tag to an activity
> Associates a tag with an activity
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/activities/{activityId}/tags":{"post":{"tags":["Activities"],"summary":"Add a tag to an activity","description":"Associates a tag with an activity","operationId":"addActivityTag","parameters":[{"name":"activityId","in":"path","required":true,"description":"Activity ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tagId"],"properties":{"tagId":{"type":"integer","description":"Tag ID to add"}}}}}},"responses":{"200":{"description":"Tag added successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Remove a tag from an activity
> Removes the association between a tag and an activity
```json
{"openapi":"3.0.3","info":{"title":"Kaana Activities API","version":"1.0.0"},"tags":[{"name":"Activities","description":"Activity management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/activities/{activityId}/tags/{tagId}":{"delete":{"tags":["Activities"],"summary":"Remove a tag from an activity","description":"Removes the association between a tag and an activity","operationId":"removeActivityTag","parameters":[{"name":"activityId","in":"path","required":true,"description":"Activity ID","schema":{"type":"integer"}},{"name":"tagId","in":"path","required":true,"description":"Tag ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Tag removed successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
# Tasks
Task management operations
## List all tasks
> Returns all tasks accessible to the authenticated user within their organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TaskWithRelations":{"allOf":[{"$ref":"#/components/schemas/Task"},{"type":"object","properties":{"assignee":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}},"milestone":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}]},"Task":{"type":"object","required":["id","title","status","priority","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique task identifier"},"title":{"type":"string","description":"Task title"},"description":{"type":"string","nullable":true,"description":"Task description"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"milestoneId":{"type":"integer","nullable":true,"description":"Associated milestone ID"},"phaseId":{"type":"integer","nullable":true,"description":"Associated phase ID"},"order":{"type":"integer","description":"Display order within the list"},"assigneeId":{"type":"integer","nullable":true,"description":"User ID of assignee"},"status":{"type":"string","enum":["todo","in_progress","review","completed"],"description":"Task status"},"priority":{"type":"string","enum":["low","medium","high"],"description":"Task priority"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Task due date"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/tasks":{"get":{"tags":["Tasks"],"summary":"List all tasks","description":"Returns all tasks accessible to the authenticated user within their organization","operationId":"listTasks","responses":{"200":{"description":"List of tasks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Create a new task
> Creates a new task within a project or organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TaskCreate":{"type":"object","required":["title","status","priority"],"properties":{"title":{"type":"string","description":"Task title"},"description":{"type":"string","nullable":true,"description":"Task description"},"projectId":{"type":"integer","nullable":true,"description":"Project to associate with"},"organizationId":{"type":"integer","nullable":true,"description":"Organization to associate with"},"milestoneId":{"type":"integer","nullable":true,"description":"Milestone to associate with"},"phaseId":{"type":"integer","nullable":true,"description":"Phase to associate with"},"assigneeId":{"type":"integer","nullable":true,"description":"User to assign the task to"},"status":{"type":"string","enum":["todo","in_progress","review","completed"]},"priority":{"type":"string","enum":["low","medium","high"]},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Due date (ISO 8601 format)"}}},"Task":{"type":"object","required":["id","title","status","priority","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique task identifier"},"title":{"type":"string","description":"Task title"},"description":{"type":"string","nullable":true,"description":"Task description"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"milestoneId":{"type":"integer","nullable":true,"description":"Associated milestone ID"},"phaseId":{"type":"integer","nullable":true,"description":"Associated phase ID"},"order":{"type":"integer","description":"Display order within the list"},"assigneeId":{"type":"integer","nullable":true,"description":"User ID of assignee"},"status":{"type":"string","enum":["todo","in_progress","review","completed"],"description":"Task status"},"priority":{"type":"string","enum":["low","medium","high"],"description":"Task priority"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Task due date"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/tasks":{"post":{"tags":["Tasks"],"summary":"Create a new task","description":"Creates a new task within a project or organization","operationId":"createTask","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"}}}},"responses":{"200":{"description":"Task created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Delete a task
> Deletes a task
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/tasks/{id}":{"delete":{"tags":["Tasks"],"summary":"Delete a task","description":"Deletes a task","operationId":"deleteTask","parameters":[{"name":"id","in":"path","required":true,"description":"Task ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Task deleted successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Task not found"},"500":{"description":"Server error"}}}}}}
```
## Update a task
> Updates an existing task
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TaskUpdate":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"milestoneId":{"type":"integer","nullable":true},"phaseId":{"type":"integer","nullable":true},"assigneeId":{"type":"integer","nullable":true},"status":{"type":"string","enum":["todo","in_progress","review","completed"]},"priority":{"type":"string","enum":["low","medium","high"]},"dueDate":{"type":"string","format":"date-time","nullable":true},"order":{"type":"integer"}}},"Task":{"type":"object","required":["id","title","status","priority","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique task identifier"},"title":{"type":"string","description":"Task title"},"description":{"type":"string","nullable":true,"description":"Task description"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"milestoneId":{"type":"integer","nullable":true,"description":"Associated milestone ID"},"phaseId":{"type":"integer","nullable":true,"description":"Associated phase ID"},"order":{"type":"integer","description":"Display order within the list"},"assigneeId":{"type":"integer","nullable":true,"description":"User ID of assignee"},"status":{"type":"string","enum":["todo","in_progress","review","completed"],"description":"Task status"},"priority":{"type":"string","enum":["low","medium","high"],"description":"Task priority"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Task due date"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/tasks/{id}":{"patch":{"tags":["Tasks"],"summary":"Update a task","description":"Updates an existing task","operationId":"updateTask","parameters":[{"name":"id","in":"path","required":true,"description":"Task ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"}}}},"responses":{"200":{"description":"Task updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Task not found"},"500":{"description":"Server error"}}}}}}
```
## Reorder tasks
> Updates the order of multiple tasks
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/tasks/reorder":{"patch":{"tags":["Tasks"],"summary":"Reorder tasks","description":"Updates the order of multiple tasks","operationId":"reorderTasks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tasks"],"properties":{"tasks":{"type":"array","items":{"type":"object","required":["id","order"],"properties":{"id":{"type":"integer"},"order":{"type":"integer"}}}}}}}}},"responses":{"200":{"description":"Tasks reordered successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## List tasks for a project
> Returns all tasks associated with a specific project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TaskWithRelations":{"allOf":[{"$ref":"#/components/schemas/Task"},{"type":"object","properties":{"assignee":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}},"project":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}},"milestone":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}]},"Task":{"type":"object","required":["id","title","status","priority","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique task identifier"},"title":{"type":"string","description":"Task title"},"description":{"type":"string","nullable":true,"description":"Task description"},"projectId":{"type":"integer","nullable":true,"description":"Associated project ID"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"milestoneId":{"type":"integer","nullable":true,"description":"Associated milestone ID"},"phaseId":{"type":"integer","nullable":true,"description":"Associated phase ID"},"order":{"type":"integer","description":"Display order within the list"},"assigneeId":{"type":"integer","nullable":true,"description":"User ID of assignee"},"status":{"type":"string","enum":["todo","in_progress","review","completed"],"description":"Task status"},"priority":{"type":"string","enum":["low","medium","high"],"description":"Task priority"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Task due date"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/projects/{projectId}/tasks":{"get":{"tags":["Tasks"],"summary":"List tasks for a project","description":"Returns all tasks associated with a specific project","operationId":"listProjectTasks","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of project tasks","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}}}}
```
## Update task phase
> Moves a task to a different phase
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tasks API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Task management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/tasks/{taskId}/phase":{"patch":{"tags":["Tasks"],"summary":"Update task phase","description":"Moves a task to a different phase","operationId":"updateTaskPhase","parameters":[{"name":"taskId","in":"path","required":true,"description":"Task ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phaseId":{"type":"integer","nullable":true,"description":"New phase ID (null to remove from phase)"}}}}}},"responses":{"200":{"description":"Task phase updated successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Task not found"},"500":{"description":"Server error"}}}}}}
```
# Documents
Document management operations
## List all documents
> Returns all documents accessible to the authenticated user within their organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"DocumentWithRelations":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"uploader":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}},"projects":{"type":"array","description":"Projects this document is linked to","items":{"type":"object","properties":{"documentId":{"type":"integer"},"projectId":{"type":"integer"},"project":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}}}}]},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents":{"get":{"tags":["Documents"],"summary":"List all documents","description":"Returns all documents accessible to the authenticated user within their organization","operationId":"listDocuments","responses":{"200":{"description":"List of documents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Create a new document
> Creates a new document record
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"DocumentCreate":{"type":"object","required":["name","type","url"],"properties":{"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to the document"},"organizationId":{"type":"integer","nullable":true,"description":"Organization to associate with"},"projectId":{"type":"integer","nullable":true,"description":"Project to link document to"}}},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents":{"post":{"tags":["Documents"],"summary":"Create a new document","description":"Creates a new document record","operationId":"createDocument","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreate"}}}},"responses":{"200":{"description":"Document created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Update a document
> Updates an existing document's metadata
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"DocumentUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"url":{"type":"string"}}},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents/{id}":{"patch":{"tags":["Documents"],"summary":"Update a document","description":"Updates an existing document's metadata","operationId":"updateDocument","parameters":[{"name":"id","in":"path","required":true,"description":"Document ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdate"}}}},"responses":{"200":{"description":"Document updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Document not found"},"500":{"description":"Server error"}}}}}}
```
## List documents for a project
> Returns all documents associated with a specific project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"DocumentWithRelations":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"uploader":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}},"projects":{"type":"array","description":"Projects this document is linked to","items":{"type":"object","properties":{"documentId":{"type":"integer"},"projectId":{"type":"integer"},"project":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"}}}}}}}}]},"Document":{"type":"object","required":["id","name","type","url","uploaderId","createdAt"],"properties":{"id":{"type":"integer","description":"Unique document identifier"},"name":{"type":"string","description":"Document name"},"description":{"type":"string","nullable":true,"description":"Document description"},"type":{"type":"string","description":"Document type/format"},"url":{"type":"string","description":"URL to access the document"},"uploaderId":{"type":"integer","description":"User ID who uploaded the document"},"organizationId":{"type":"integer","nullable":true,"description":"Associated organization ID"},"createdAt":{"type":"string","format":"date-time","description":"Upload timestamp"}}}}},"paths":{"/documents/{projectId}":{"get":{"tags":["Documents"],"summary":"List documents for a project","description":"Returns all documents associated with a specific project","operationId":"listProjectDocuments","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of project documents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentWithRelations"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Link document to project
> Associates a document with a project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/documents/{documentId}/projects/{projectId}":{"post":{"tags":["Documents"],"summary":"Link document to project","description":"Associates a document with a project","operationId":"linkDocumentToProject","parameters":[{"name":"documentId","in":"path","required":true,"description":"Document ID","schema":{"type":"integer"}},{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Document linked to project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Document or project not found"},"500":{"description":"Server error"}}}}}}
```
## Unlink document from project
> Removes the association between a document and a project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/documents/{documentId}/projects/{projectId}":{"delete":{"tags":["Documents"],"summary":"Unlink document from project","description":"Removes the association between a document and a project","operationId":"unlinkDocumentFromProject","parameters":[{"name":"documentId","in":"path","required":true,"description":"Document ID","schema":{"type":"integer"}},{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Document unlinked from project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Association not found"},"500":{"description":"Server error"}}}}}}
```
## Upload a file
> Uploads a file and returns the file URL
```json
{"openapi":"3.0.3","info":{"title":"Kaana Documents API","version":"1.0.0"},"tags":[{"name":"Documents","description":"Document management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/upload":{"post":{"tags":["Documents"],"summary":"Upload a file","description":"Uploads a file and returns the file URL","operationId":"uploadFile","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file to upload"}}}}}},"responses":{"200":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"URL of the uploaded file"}}}}}},"400":{"description":"No file uploaded"},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
# Milestones
Milestone management operations
## Create a new milestone
> Creates a new milestone within a project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneCreate":{"type":"object","required":["title","projectId"],"properties":{"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Project to create milestone in"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Start date (ISO 8601 format)"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Due date (ISO 8601 format)"},"status":{"type":"string","enum":["pending","in_progress","completed"],"default":"pending"}}},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/milestones":{"post":{"tags":["Milestones"],"summary":"Create a new milestone","description":"Creates a new milestone within a project","operationId":"createMilestone","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneCreate"}}}},"responses":{"200":{"description":"Milestone created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Milestone"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Get a milestone
> Returns a specific milestone with its tasks
```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneWithTasks":{"allOf":[{"$ref":"#/components/schemas/Milestone"},{"type":"object","properties":{"tasks":{"type":"array","description":"Tasks associated with this milestone","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"}}}}}}]},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/milestones/{id}":{"get":{"tags":["Milestones"],"summary":"Get a milestone","description":"Returns a specific milestone with its tasks","operationId":"getMilestone","parameters":[{"name":"id","in":"path","required":true,"description":"Milestone ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Milestone details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneWithTasks"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Milestone not found"},"500":{"description":"Server error"}}}}}}
```
## Update a milestone
> Updates an existing milestone
```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneUpdate":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"dueDate":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["pending","in_progress","completed"]}}},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/milestones/{id}":{"put":{"tags":["Milestones"],"summary":"Update a milestone","description":"Updates an existing milestone","operationId":"updateMilestone","parameters":[{"name":"id","in":"path","required":true,"description":"Milestone ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MilestoneUpdate"}}}},"responses":{"200":{"description":"Milestone updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Milestone"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Milestone not found"},"500":{"description":"Server error"}}}}}}
```
## Delete a milestone
> Deletes a milestone. Tasks associated with the milestone will be unlinked.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/milestones/{id}":{"delete":{"tags":["Milestones"],"summary":"Delete a milestone","description":"Deletes a milestone. Tasks associated with the milestone will be unlinked.","operationId":"deleteMilestone","parameters":[{"name":"id","in":"path","required":true,"description":"Milestone ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Milestone deleted successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Milestone not found"},"500":{"description":"Server error"}}}}}}
```
## List milestones for a project
> Returns all milestones associated with a specific project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Milestones API","version":"1.0.0"},"tags":[{"name":"Milestones","description":"Milestone management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"MilestoneWithTasks":{"allOf":[{"$ref":"#/components/schemas/Milestone"},{"type":"object","properties":{"tasks":{"type":"array","description":"Tasks associated with this milestone","items":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"}}}}}}]},"Milestone":{"type":"object","required":["id","title","projectId","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique milestone identifier"},"title":{"type":"string","description":"Milestone title"},"description":{"type":"string","nullable":true,"description":"Milestone description"},"projectId":{"type":"integer","description":"Associated project ID"},"startDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone start date"},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"Milestone due date"},"status":{"type":"string","enum":["pending","in_progress","completed"],"description":"Milestone status"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/projects/{projectId}/milestones":{"get":{"tags":["Milestones"],"summary":"List milestones for a project","description":"Returns all milestones associated with a specific project","operationId":"listProjectMilestones","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of project milestones","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MilestoneWithTasks"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Project not found"},"500":{"description":"Server error"}}}}}}
```
# Tags
Tag management operations
## List all tags
> Returns all tags accessible to the authenticated user
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Tag":{"type":"object","required":["id","name","color","isGlobal","createdAt"],"properties":{"id":{"type":"integer","description":"Unique tag identifier"},"name":{"type":"string","description":"Tag name"},"color":{"type":"string","description":"Tag color (hex code)"},"categoryId":{"type":"integer","nullable":true,"description":"Parent category ID"},"parentId":{"type":"integer","nullable":true,"description":"Parent tag ID for hierarchical tags"},"isGlobal":{"type":"boolean","description":"Whether the tag is available globally"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/tags":{"get":{"tags":["Tags"],"summary":"List all tags","description":"Returns all tags accessible to the authenticated user","operationId":"listTags","responses":{"200":{"description":"List of tags","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
## Create a new tag
> Creates a new tag. Requires manage\_tags permission.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TagCreate":{"type":"object","required":["name","color"],"properties":{"name":{"type":"string","description":"Tag name"},"color":{"type":"string","description":"Tag color (hex code)"},"categoryId":{"type":"integer","nullable":true,"description":"Parent category ID"},"parentId":{"type":"integer","nullable":true,"description":"Parent tag ID"},"isGlobal":{"type":"boolean","default":true}}},"Tag":{"type":"object","required":["id","name","color","isGlobal","createdAt"],"properties":{"id":{"type":"integer","description":"Unique tag identifier"},"name":{"type":"string","description":"Tag name"},"color":{"type":"string","description":"Tag color (hex code)"},"categoryId":{"type":"integer","nullable":true,"description":"Parent category ID"},"parentId":{"type":"integer","nullable":true,"description":"Parent tag ID for hierarchical tags"},"isGlobal":{"type":"boolean","description":"Whether the tag is available globally"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"}}}}},"paths":{"/tags":{"post":{"tags":["Tags"],"summary":"Create a new tag","description":"Creates a new tag. Requires manage_tags permission.","operationId":"createTag","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagCreate"}}}},"responses":{"200":{"description":"Tag created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Add a tag to a project
> Associates a tag with a project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/projects/{projectId}/tags":{"post":{"tags":["Tags"],"summary":"Add a tag to a project","description":"Associates a tag with a project","operationId":"addProjectTag","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tagId"],"properties":{"tagId":{"type":"integer","description":"Tag ID to add"}}}}}},"responses":{"200":{"description":"Tag added to project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Project or tag not found"},"500":{"description":"Server error"}}}}}}
```
## Remove a tag from a project
> Removes the association between a tag and a project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/projects/{projectId}/tags/{tagId}":{"delete":{"tags":["Tags"],"summary":"Remove a tag from a project","description":"Removes the association between a tag and a project","operationId":"removeProjectTag","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}},{"name":"tagId","in":"path","required":true,"description":"Tag ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Tag removed from project successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Association not found"},"500":{"description":"Server error"}}}}}}
```
## Manage project tags
> Updates the set of tags associated with a project
```json
{"openapi":"3.0.3","info":{"title":"Kaana Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Tag management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/projects/{projectId}/project-tags":{"post":{"tags":["Tags"],"summary":"Manage project tags","description":"Updates the set of tags associated with a project","operationId":"manageProjectTags","parameters":[{"name":"projectId","in":"path","required":true,"description":"Project ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tagIds"],"properties":{"tagIds":{"type":"array","items":{"type":"integer"},"description":"List of tag IDs to associate with the project"}}}}}},"responses":{"200":{"description":"Project tags updated successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
# Entities
# Organizations
Organization (entity/account) management operations
## List all organizations
> Returns all organizations accessible to the authenticated user
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Organization":{"type":"object","required":["id","name","type","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"],"description":"Organization type"},"status":{"type":"string","enum":["active","inactive","churned"],"description":"Organization status"},"industry":{"type":"string","nullable":true,"description":"Industry category"},"website":{"type":"string","nullable":true,"description":"Organization website URL"},"description":{"type":"string","nullable":true,"description":"Organization description"},"metadata":{"type":"object","nullable":true,"description":"Additional organization metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/organizations":{"get":{"tags":["Organizations"],"summary":"List all organizations","description":"Returns all organizations accessible to the authenticated user","operationId":"listOrganizations","responses":{"200":{"description":"List of organizations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Create a new organization
> Creates a new organization. Requires consultant or admin role.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"OrganizationCreate":{"type":"object","required":["name","type","status"],"properties":{"name":{"type":"string","description":"Organization name"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"]},"status":{"type":"string","enum":["active","inactive","churned"],"default":"active"},"industry":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}}},"Organization":{"type":"object","required":["id","name","type","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"],"description":"Organization type"},"status":{"type":"string","enum":["active","inactive","churned"],"description":"Organization status"},"industry":{"type":"string","nullable":true,"description":"Industry category"},"website":{"type":"string","nullable":true,"description":"Organization website URL"},"description":{"type":"string","nullable":true,"description":"Organization description"},"metadata":{"type":"object","nullable":true,"description":"Additional organization metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/organizations":{"post":{"tags":["Organizations"],"summary":"Create a new organization","description":"Creates a new organization. Requires consultant or admin role.","operationId":"createOrganization","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCreate"}}}},"responses":{"200":{"description":"Organization created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Get an organization
> Returns a specific organization by ID
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Organization":{"type":"object","required":["id","name","type","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"],"description":"Organization type"},"status":{"type":"string","enum":["active","inactive","churned"],"description":"Organization status"},"industry":{"type":"string","nullable":true,"description":"Industry category"},"website":{"type":"string","nullable":true,"description":"Organization website URL"},"description":{"type":"string","nullable":true,"description":"Organization description"},"metadata":{"type":"object","nullable":true,"description":"Additional organization metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/organizations/{id}":{"get":{"tags":["Organizations"],"summary":"Get an organization","description":"Returns a specific organization by ID","operationId":"getOrganization","parameters":[{"name":"id","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Organization details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Organization not found"},"500":{"description":"Server error"}}}}}}
```
## Update an organization
> Updates an existing organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"OrganizationUpdate":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"]},"status":{"type":"string","enum":["active","inactive","churned"]},"industry":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}}},"Organization":{"type":"object","required":["id","name","type","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"],"description":"Organization type"},"status":{"type":"string","enum":["active","inactive","churned"],"description":"Organization status"},"industry":{"type":"string","nullable":true,"description":"Industry category"},"website":{"type":"string","nullable":true,"description":"Organization website URL"},"description":{"type":"string","nullable":true,"description":"Organization description"},"metadata":{"type":"object","nullable":true,"description":"Additional organization metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/organizations/{id}":{"put":{"tags":["Organizations"],"summary":"Update an organization","description":"Updates an existing organization","operationId":"updateOrganization","parameters":[{"name":"id","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationUpdate"}}}},"responses":{"200":{"description":"Organization updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Organization not found"},"500":{"description":"Server error"}}}}}}
```
## Delete an organization
> Deletes an organization. Requires consultant or admin role.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{id}":{"delete":{"tags":["Organizations"],"summary":"Delete an organization","description":"Deletes an organization. Requires consultant or admin role.","operationId":"deleteOrganization","parameters":[{"name":"id","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Organization deleted successfully"},"400":{"description":"Cannot delete organization with related items"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Organization not found"},"500":{"description":"Server error"}}}}}}
```
## Duplicate an organization
> Creates a copy of an existing organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Organization":{"type":"object","required":["id","name","type","status","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique organization identifier"},"name":{"type":"string","description":"Organization name"},"type":{"type":"string","enum":["customer","partner","vendor","prospect"],"description":"Organization type"},"status":{"type":"string","enum":["active","inactive","churned"],"description":"Organization status"},"industry":{"type":"string","nullable":true,"description":"Industry category"},"website":{"type":"string","nullable":true,"description":"Organization website URL"},"description":{"type":"string","nullable":true,"description":"Organization description"},"metadata":{"type":"object","nullable":true,"description":"Additional organization metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/organizations/{id}/duplicate":{"post":{"tags":["Organizations"],"summary":"Duplicate an organization","description":"Creates a copy of an existing organization","operationId":"duplicateOrganization","parameters":[{"name":"id","in":"path","required":true,"description":"Organization ID to duplicate","schema":{"type":"integer"}}],"responses":{"200":{"description":"Organization duplicated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Organization not found"},"500":{"description":"Server error"}}}}}}
```
## List tasks for an organization
> Returns all tasks associated with a specific organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{organizationId}/tasks":{"get":{"tags":["Organizations"],"summary":"List tasks for an organization","description":"Returns all tasks associated with a specific organization","operationId":"listOrganizationTasks","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of organization tasks","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## List projects for an organization
> Returns all projects associated with a specific organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{organizationId}/projects":{"get":{"tags":["Organizations"],"summary":"List projects for an organization","description":"Returns all projects associated with a specific organization","operationId":"listOrganizationProjects","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of organization projects","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## List documents for an organization
> Returns all documents associated with a specific organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{organizationId}/documents":{"get":{"tags":["Organizations"],"summary":"List documents for an organization","description":"Returns all documents associated with a specific organization","operationId":"listOrganizationDocuments","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of organization documents","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## List members of an organization
> Returns all contact members of a specific organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"OrganizationMember":{"type":"object","properties":{"organizationId":{"type":"integer"},"contactId":{"type":"integer"},"role":{"type":"string","enum":["primary","secondary","observer"]},"contact":{"type":"object","properties":{"id":{"type":"integer"},"fullName":{"type":"string"},"email":{"type":"string"},"title":{"type":"string","nullable":true}}}}}}},"paths":{"/organizations/{organizationId}/members":{"get":{"tags":["Organizations"],"summary":"List members of an organization","description":"Returns all contact members of a specific organization","operationId":"listOrganizationMembers","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of organization members","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMember"}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
## Add a member to an organization
> Associates a contact with an organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{organizationId}/members":{"post":{"tags":["Organizations"],"summary":"Add a member to an organization","description":"Associates a contact with an organization","operationId":"addOrganizationMember","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contactId","role"],"properties":{"contactId":{"type":"integer","description":"Contact ID to add"},"role":{"type":"string","enum":["primary","secondary","observer"],"description":"Member role"}}}}}},"responses":{"200":{"description":"Member added successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Remove a member from an organization
> Removes the association between a contact and an organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{organizationId}/members/{contactId}":{"delete":{"tags":["Organizations"],"summary":"Remove a member from an organization","description":"Removes the association between a contact and an organization","operationId":"removeOrganizationMember","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}},{"name":"contactId","in":"path","required":true,"description":"Contact ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Member removed successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Member not found"},"500":{"description":"Server error"}}}}}}
```
## Update an organization member
> Updates a member's role in the organization
```json
{"openapi":"3.0.3","info":{"title":"Kaana Organizations API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization (entity/account) management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/organizations/{organizationId}/members/{contactId}":{"patch":{"tags":["Organizations"],"summary":"Update an organization member","description":"Updates a member's role in the organization","operationId":"updateOrganizationMember","parameters":[{"name":"organizationId","in":"path","required":true,"description":"Organization ID","schema":{"type":"integer"}},{"name":"contactId","in":"path","required":true,"description":"Contact ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["primary","secondary","observer"]}}}}}},"responses":{"200":{"description":"Member updated successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Member not found"},"500":{"description":"Server error"}}}}}}
```
# Contacts
Contact management operations
## List all contacts
> Returns all contacts accessible to the authenticated user
```json
{"openapi":"3.0.3","info":{"title":"Kaana Contacts API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Contact management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Contact":{"type":"object","required":["id","fullName","email","type","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique contact identifier"},"fullName":{"type":"string","description":"Contact's full name"},"mentionName":{"type":"string","nullable":true,"description":"Short name for @mentions"},"email":{"type":"string","format":"email","description":"Contact email address"},"phone":{"type":"string","nullable":true,"description":"Contact phone number"},"company":{"type":"string","nullable":true,"description":"Company name"},"title":{"type":"string","nullable":true,"description":"Job title"},"department":{"type":"string","nullable":true,"description":"Department"},"type":{"type":"string","enum":["internal","external","vendor","client"],"description":"Contact type"},"isActive":{"type":"boolean","description":"Whether the contact is active"},"metadata":{"type":"object","nullable":true,"description":"Additional contact metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/contacts":{"get":{"tags":["Contacts"],"summary":"List all contacts","description":"Returns all contacts accessible to the authenticated user","operationId":"listContacts","responses":{"200":{"description":"List of contacts","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Create a new contact
> Creates a new contact. Requires consultant or admin role.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Contacts API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Contact management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ContactCreate":{"type":"object","required":["fullName","email","type"],"properties":{"fullName":{"type":"string","description":"Contact's full name"},"mentionName":{"type":"string","nullable":true,"description":"Short name for @mentions"},"email":{"type":"string","format":"email","description":"Contact email address (must be unique)"},"phone":{"type":"string","nullable":true,"description":"Contact phone number"},"company":{"type":"string","nullable":true,"description":"Company name"},"title":{"type":"string","nullable":true,"description":"Job title"},"department":{"type":"string","nullable":true,"description":"Department"},"type":{"type":"string","enum":["internal","external","vendor","client"]},"isActive":{"type":"boolean","default":true},"metadata":{"type":"object","nullable":true},"canLogin":{"type":"boolean","default":false,"description":"Whether to create a user account for this contact"}}},"Contact":{"type":"object","required":["id","fullName","email","type","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique contact identifier"},"fullName":{"type":"string","description":"Contact's full name"},"mentionName":{"type":"string","nullable":true,"description":"Short name for @mentions"},"email":{"type":"string","format":"email","description":"Contact email address"},"phone":{"type":"string","nullable":true,"description":"Contact phone number"},"company":{"type":"string","nullable":true,"description":"Company name"},"title":{"type":"string","nullable":true,"description":"Job title"},"department":{"type":"string","nullable":true,"description":"Department"},"type":{"type":"string","enum":["internal","external","vendor","client"],"description":"Contact type"},"isActive":{"type":"boolean","description":"Whether the contact is active"},"metadata":{"type":"object","nullable":true,"description":"Additional contact metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/contacts":{"post":{"tags":["Contacts"],"summary":"Create a new contact","description":"Creates a new contact. Requires consultant or admin role.","operationId":"createContact","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactCreate"}}}},"responses":{"200":{"description":"Contact created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"description":"Validation error or email already exists"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## List contacts for mentions
> Returns contacts formatted for @mention functionality
```json
{"openapi":"3.0.3","info":{"title":"Kaana Contacts API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Contact management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/contacts/mentions":{"get":{"tags":["Contacts"],"summary":"List contacts for mentions","description":"Returns contacts formatted for @mention functionality","operationId":"listContactsForMentions","responses":{"200":{"description":"List of mentionable contacts","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"fullName":{"type":"string"},"mentionName":{"type":"string","nullable":true},"email":{"type":"string"}}}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
# System Feed
# System Feed
Signal detection and lifecycle management
## List signals
> Returns paginated list of system feed signals with optional filtering
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Signal":{"type":"object","required":["id","title","summary","severity","status","category","integrationName","createdAt"],"properties":{"id":{"type":"integer","description":"Unique signal identifier"},"fingerprint":{"type":"string","description":"Unique fingerprint for deduplication"},"title":{"type":"string","description":"Signal title"},"summary":{"type":"string","description":"Brief summary of the issue"},"analysis":{"type":"string","nullable":true,"description":"AI-generated analysis"},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Signal severity level"},"status":{"type":"string","enum":["active","acknowledged","assigned","in_progress","resolved","dismissed"],"description":"Current lifecycle status"},"category":{"type":"string","description":"Signal category"},"integrationId":{"type":"integer","nullable":true,"description":"Source integration ID"},"integrationName":{"type":"string","description":"Source integration name"},"integrationType":{"type":"string","enum":["stripe","zuora","salesforce"],"description":"Integration type"},"suggestedActions":{"type":"array","items":{"type":"string"},"description":"AI-suggested resolution actions"},"metrics":{"type":"object","nullable":true,"description":"Signal-specific metrics"},"priority":{"type":"string","nullable":true,"enum":["low","medium","high","critical"]},"assigneeId":{"type":"integer","nullable":true},"eventCount":{"type":"integer","description":"Number of related events"},"firstSeen":{"type":"string","format":"date-time"},"lastSeen":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"paths":{"/concierge/alerts":{"get":{"tags":["System Feed"],"summary":"List signals","description":"Returns paginated list of system feed signals with optional filtering","operationId":"listAlerts","parameters":[{"name":"status","in":"query","description":"Filter by signal status","schema":{"type":"string","enum":["active","acknowledged","assigned","in_progress","resolved","dismissed"]}},{"name":"severity","in":"query","description":"Filter by severity level","schema":{"type":"string","enum":["critical","warning","info"]}},{"name":"integrationId","in":"query","description":"Filter by integration ID","schema":{"type":"integer"}},{"name":"page","in":"query","description":"Page number (default 1)","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","description":"Items per page (default 10)","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Paginated list of signals","content":{"application/json":{"schema":{"type":"object","properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Get signal statistics
> Returns aggregated statistics about signals
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"SignalStats":{"type":"object","properties":{"total":{"type":"integer"},"bySeverity":{"type":"object","properties":{"critical":{"type":"integer"},"warning":{"type":"integer"},"info":{"type":"integer"}}},"byStatus":{"type":"object","properties":{"active":{"type":"integer"},"acknowledged":{"type":"integer"},"resolved":{"type":"integer"}}},"byCategory":{"type":"object","additionalProperties":{"type":"integer"}}}}}},"paths":{"/concierge/alerts/stats":{"get":{"tags":["System Feed"],"summary":"Get signal statistics","description":"Returns aggregated statistics about signals","operationId":"getAlertStats","responses":{"200":{"description":"Signal statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalStats"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Get signal details
> Returns detailed information about a specific signal
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"SignalDetail":{"allOf":[{"$ref":"#/components/schemas/Signal"},{"type":"object","properties":{"affectedEntities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"}}}},"initialGuess":{"type":"string","description":"AI initial assessment before deep analysis"}}}]},"Signal":{"type":"object","required":["id","title","summary","severity","status","category","integrationName","createdAt"],"properties":{"id":{"type":"integer","description":"Unique signal identifier"},"fingerprint":{"type":"string","description":"Unique fingerprint for deduplication"},"title":{"type":"string","description":"Signal title"},"summary":{"type":"string","description":"Brief summary of the issue"},"analysis":{"type":"string","nullable":true,"description":"AI-generated analysis"},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Signal severity level"},"status":{"type":"string","enum":["active","acknowledged","assigned","in_progress","resolved","dismissed"],"description":"Current lifecycle status"},"category":{"type":"string","description":"Signal category"},"integrationId":{"type":"integer","nullable":true,"description":"Source integration ID"},"integrationName":{"type":"string","description":"Source integration name"},"integrationType":{"type":"string","enum":["stripe","zuora","salesforce"],"description":"Integration type"},"suggestedActions":{"type":"array","items":{"type":"string"},"description":"AI-suggested resolution actions"},"metrics":{"type":"object","nullable":true,"description":"Signal-specific metrics"},"priority":{"type":"string","nullable":true,"enum":["low","medium","high","critical"]},"assigneeId":{"type":"integer","nullable":true},"eventCount":{"type":"integer","description":"Number of related events"},"firstSeen":{"type":"string","format":"date-time"},"lastSeen":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/concierge/alerts/{id}":{"get":{"tags":["System Feed"],"summary":"Get signal details","description":"Returns detailed information about a specific signal","operationId":"getAlert","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Signal details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalDetail"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Update signal status
> Updates the lifecycle status of a signal
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/alerts/{id}":{"patch":{"tags":["System Feed"],"summary":"Update signal status","description":"Updates the lifecycle status of a signal","operationId":"updateAlertStatus","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","acknowledged","assigned","in_progress","resolved","dismissed"]}}}}}},"responses":{"200":{"description":"Signal status updated","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"description":"Invalid status"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Generate AI insight
> Generates deeper AI-powered analysis and recommendations for a signal. Requires feedAI plan feature.
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/alerts/{id}/insight":{"post":{"tags":["System Feed"],"summary":"Generate AI insight","description":"Generates deeper AI-powered analysis and recommendations for a signal. Requires feedAI plan feature.","operationId":"generateAlertInsight","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"AI insight generated","content":{"application/json":{"schema":{"type":"object","properties":{"insight":{"type":"string","description":"Detailed AI analysis with root cause, impact, and resolution guidance"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or plan feature not available"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Get signal raw data
> Returns the raw event data associated with a signal
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"RawEvent":{"type":"object","properties":{"id":{"type":"integer"},"eventType":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"severity":{"type":"string"},"payload":{"type":"object"},"metadata":{"type":"object"}}}}},"paths":{"/concierge/alerts/{id}/raw-data":{"get":{"tags":["System Feed"],"summary":"Get signal raw data","description":"Returns the raw event data associated with a signal","operationId":"getAlertRawData","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Raw event data","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/RawEvent"}}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Assign signal to user
> Assigns a signal to a specific user for investigation
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/alerts/{id}/assign":{"post":{"tags":["System Feed"],"summary":"Assign signal to user","description":"Assigns a signal to a specific user for investigation","operationId":"assignAlert","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assigneeId"],"properties":{"assigneeId":{"type":"integer","description":"User ID to assign the signal to"}}}}}},"responses":{"200":{"description":"Signal assigned successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Update signal priority
> Updates the priority level of a signal
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/alerts/{id}/priority":{"post":{"tags":["System Feed"],"summary":"Update signal priority","description":"Updates the priority level of a signal","operationId":"updateAlertPriority","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["priority"],"properties":{"priority":{"type":"string","enum":["low","medium","high","critical"]}}}}}},"responses":{"200":{"description":"Priority updated successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Add comment to signal
> Adds a comment to a signal's history
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/alerts/{id}/comment":{"post":{"tags":["System Feed"],"summary":"Add comment to signal","description":"Adds a comment to a signal's history","operationId":"addAlertComment","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["comment"],"properties":{"comment":{"type":"string","description":"Comment text"}}}}}},"responses":{"200":{"description":"Comment added successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Get signal history
> Returns the full audit history of a signal including status changes, assignments, and comments
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"SignalHistoryEntry":{"type":"object","properties":{"id":{"type":"integer"},"alertId":{"type":"integer"},"action":{"type":"string","enum":["created","status_changed","assigned","commented","priority_changed","resolution_started","resolution_completed"]},"previousValue":{"type":"string","nullable":true},"newValue":{"type":"string","nullable":true},"comment":{"type":"string","nullable":true},"userId":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/concierge/alerts/{id}/history":{"get":{"tags":["System Feed"],"summary":"Get signal history","description":"Returns the full audit history of a signal including status changes, assignments, and comments","operationId":"getAlertHistory","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Signal history","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SignalHistoryEntry"}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
## Link signal to support ticket
> Associates a signal with a support ticket
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/alerts/{id}/link-ticket":{"post":{"tags":["System Feed"],"summary":"Link signal to support ticket","description":"Associates a signal with a support ticket","operationId":"linkAlertToTicket","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ticketId"],"properties":{"ticketId":{"type":"integer","description":"Support ticket ID to link"}}}}}},"responses":{"200":{"description":"Ticket linked successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Trigger anomaly analysis
> Ingests fresh events from connected integrations, detects anomalies, and generates AI-powered signals. Requires feedAI plan feature.
```json
{"openapi":"3.0.3","info":{"title":"Kaana System Feed API","version":"1.0.0"},"tags":[{"name":"System Feed","description":"Signal detection and lifecycle management"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Signal":{"type":"object","required":["id","title","summary","severity","status","category","integrationName","createdAt"],"properties":{"id":{"type":"integer","description":"Unique signal identifier"},"fingerprint":{"type":"string","description":"Unique fingerprint for deduplication"},"title":{"type":"string","description":"Signal title"},"summary":{"type":"string","description":"Brief summary of the issue"},"analysis":{"type":"string","nullable":true,"description":"AI-generated analysis"},"severity":{"type":"string","enum":["critical","warning","info"],"description":"Signal severity level"},"status":{"type":"string","enum":["active","acknowledged","assigned","in_progress","resolved","dismissed"],"description":"Current lifecycle status"},"category":{"type":"string","description":"Signal category"},"integrationId":{"type":"integer","nullable":true,"description":"Source integration ID"},"integrationName":{"type":"string","description":"Source integration name"},"integrationType":{"type":"string","enum":["stripe","zuora","salesforce"],"description":"Integration type"},"suggestedActions":{"type":"array","items":{"type":"string"},"description":"AI-suggested resolution actions"},"metrics":{"type":"object","nullable":true,"description":"Signal-specific metrics"},"priority":{"type":"string","nullable":true,"enum":["low","medium","high","critical"]},"assigneeId":{"type":"integer","nullable":true},"eventCount":{"type":"integer","description":"Number of related events"},"firstSeen":{"type":"string","format":"date-time"},"lastSeen":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/concierge/analyze":{"post":{"tags":["System Feed"],"summary":"Trigger anomaly analysis","description":"Ingests fresh events from connected integrations, detects anomalies, and generates AI-powered signals. Requires feedAI plan feature.","operationId":"analyzeAnomalies","responses":{"200":{"description":"Analysis completed","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"alertIds":{"type":"array","items":{"type":"integer"}}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or plan feature not available"},"500":{"description":"Server error"}}}}}}
```
# Service Requests
# Service Requests
Service request management operations
## Create a service request
> Creates a new internal service request
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Service Requests","description":"Service request management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ServiceRequestCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","description":"Service request title"},"description":{"type":"string","nullable":true,"description":"Detailed description"},"priority":{"type":"string","enum":["low","medium","high","urgent"],"default":"medium"},"category":{"type":"string","nullable":true},"referenceType":{"type":"string","nullable":true,"enum":["project","organization"]},"referenceId":{"type":"integer","nullable":true}}},"ServiceRequest":{"type":"object","required":["id","title","status","priority","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique service request identifier"},"title":{"type":"string","description":"Service request title"},"description":{"type":"string","nullable":true,"description":"Detailed description of the request"},"status":{"type":"string","enum":["open","in_progress","pending","resolved","closed"],"description":"Current status"},"priority":{"type":"string","enum":["low","medium","high","urgent"],"description":"Priority level"},"category":{"type":"string","nullable":true,"description":"Request category"},"creatorId":{"type":"integer","description":"User ID who created the request"},"assigneeId":{"type":"integer","nullable":true,"description":"User ID assigned to the request"},"referenceType":{"type":"string","nullable":true,"description":"Type of linked reference (project, organization)"},"referenceId":{"type":"integer","nullable":true,"description":"ID of the linked reference"},"metadata":{"type":"object","nullable":true,"description":"Additional request metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/managed-services/request":{"post":{"tags":["Service Requests"],"summary":"Create a service request","description":"Creates a new internal service request","operationId":"createServiceRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequestCreate"}}}},"responses":{"200":{"description":"Service request created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceRequest"}}}},"400":{"description":"Validation error"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
## Delete a service request
> Deletes an internal service request
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Service Requests","description":"Service request management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/service-requests/{id}":{"delete":{"tags":["Service Requests"],"summary":"Delete a service request","description":"Deletes an internal service request","operationId":"deleteServiceRequest","parameters":[{"name":"id","in":"path","required":true,"description":"Service request ID","schema":{"type":"integer"}}],"responses":{"204":{"description":"Service request deleted successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Service request not found"},"500":{"description":"Server error"}}}}}}
```
## List comments on a service request
> Returns all comments for a specific service request
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Service Requests","description":"Service request management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Comment":{"type":"object","required":["id","content","userId","createdAt","updatedAt"],"properties":{"id":{"type":"integer"},"content":{"type":"string"},"serviceRequestId":{"type":"integer","nullable":true},"userId":{"type":"integer"},"parentId":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}}}}}},"paths":{"/service-requests/{serviceRequestId}/comments":{"get":{"tags":["Service Requests"],"summary":"List comments on a service request","description":"Returns all comments for a specific service request","operationId":"listServiceRequestComments","parameters":[{"name":"serviceRequestId","in":"path","required":true,"description":"Service request ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"List of comments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
## Add a comment to a service request
> Creates a new comment on a service request
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Service Requests","description":"Service request management operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"Comment":{"type":"object","required":["id","content","userId","createdAt","updatedAt"],"properties":{"id":{"type":"integer"},"content":{"type":"string"},"serviceRequestId":{"type":"integer","nullable":true},"userId":{"type":"integer"},"parentId":{"type":"integer","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"integer"},"username":{"type":"string"},"fullName":{"type":"string"}}}}}}},"paths":{"/service-requests/{serviceRequestId}/comments":{"post":{"tags":["Service Requests"],"summary":"Add a comment to a service request","description":"Creates a new comment on a service request","operationId":"createServiceRequestComment","parameters":[{"name":"serviceRequestId","in":"path","required":true,"description":"Service request ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Comment content"},"parentId":{"type":"integer","nullable":true,"description":"Parent comment ID for replies"}}}}}},"responses":{"200":{"description":"Comment created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"500":{"description":"Server error"}}}}}}
```
# Managed Services
Managed services dashboard and ticket operations
## Get managed services dashboard
> Returns dashboard data including service requests, tickets, and activity feed
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Managed Services","description":"Managed services dashboard and ticket operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"DashboardData":{"type":"object","properties":{"serviceRequests":{"type":"array","items":{"$ref":"#/components/schemas/ServiceRequest"}},"tickets":{"type":"array","items":{"type":"object"}},"metrics":{"type":"object","properties":{"activeEngagements":{"type":"integer"},"avgResolutionTime":{"type":"number"},"hoursSaved":{"type":"number"}}},"activityFeed":{"type":"array","items":{"type":"object"}}}},"ServiceRequest":{"type":"object","required":["id","title","status","priority","creatorId","createdAt","updatedAt"],"properties":{"id":{"type":"integer","description":"Unique service request identifier"},"title":{"type":"string","description":"Service request title"},"description":{"type":"string","nullable":true,"description":"Detailed description of the request"},"status":{"type":"string","enum":["open","in_progress","pending","resolved","closed"],"description":"Current status"},"priority":{"type":"string","enum":["low","medium","high","urgent"],"description":"Priority level"},"category":{"type":"string","nullable":true,"description":"Request category"},"creatorId":{"type":"integer","description":"User ID who created the request"},"assigneeId":{"type":"integer","nullable":true,"description":"User ID assigned to the request"},"referenceType":{"type":"string","nullable":true,"description":"Type of linked reference (project, organization)"},"referenceId":{"type":"integer","nullable":true,"description":"ID of the linked reference"},"metadata":{"type":"object","nullable":true,"description":"Additional request metadata"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}},"paths":{"/managed-services/dashboard":{"get":{"tags":["Managed Services"],"summary":"Get managed services dashboard","description":"Returns dashboard data including service requests, tickets, and activity feed","operationId":"getManagedServicesDashboard","responses":{"200":{"description":"Dashboard data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardData"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"500":{"description":"Server error"}}}}}}
```
## Get ticket details
> Returns details of a specific support ticket including conversation history
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Managed Services","description":"Managed services dashboard and ticket operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"TicketWithConversation":{"type":"object","properties":{"ticket":{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":"string"},"status":{"type":"string"},"priority":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"content":{"type":"string"},"sender":{"type":"object","properties":{"name":{"type":"string"},"isSupport":{"type":"boolean"}}},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"paths":{"/managed-services/ticket/{ticketId}":{"get":{"tags":["Managed Services"],"summary":"Get ticket details","description":"Returns details of a specific support ticket including conversation history","operationId":"getTicket","parameters":[{"name":"ticketId","in":"path","required":true,"description":"Ticket ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Ticket details with conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketWithConversation"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Access denied"},"404":{"description":"Ticket not found"},"500":{"description":"Server error"}}}}}}
```
## Reply to a ticket
> Adds a reply to an existing support ticket
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Managed Services","description":"Managed services dashboard and ticket operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/managed-services/ticket/{ticketId}/reply":{"post":{"tags":["Managed Services"],"summary":"Reply to a ticket","description":"Adds a reply to an existing support ticket","operationId":"replyToTicket","parameters":[{"name":"ticketId","in":"path","required":true,"description":"Ticket ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Reply content"}}}}}},"responses":{"200":{"description":"Reply added successfully"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied"},"404":{"description":"Ticket not found"},"500":{"description":"Server error"}}}}}}
```
## Search for reference items
> Searches projects, organizations, and other items for linking to service requests
```json
{"openapi":"3.0.3","info":{"title":"Kaana Service Requests API","version":"1.0.0"},"tags":[{"name":"Managed Services","description":"Managed services dashboard and ticket operations"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/managed-services/search-references":{"get":{"tags":["Managed Services"],"summary":"Search for reference items","description":"Searches projects, organizations, and other items for linking to service requests","operationId":"searchReferences","parameters":[{"name":"query","in":"query","description":"Search query","schema":{"type":"string"}},{"name":"type","in":"query","description":"Filter by reference type","schema":{"type":"string","enum":["project","organization","document"]}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true}}}}}}},"401":{"description":"Not authenticated"},"500":{"description":"Server error"}}}}}}
```
# AI & Kai
# Kai Resolution Agent
Kai resolution agent session management and action execution
## Start agent session
> Initiates a new Kai resolution agent session for a signal. \
> The agent will analyze the signal and prepare to propose resolution actions.\
> Requires create\_agent\_remediation permission and agentAI plan feature.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"AgentSession":{"type":"object","required":["id","alertId","status","createdAt"],"properties":{"id":{"type":"integer","description":"Unique session identifier"},"alertId":{"type":"integer","description":"Associated signal ID"},"status":{"type":"string","enum":["started","analyzing","awaiting_confirmation","executing","completed","failed","cancelled"],"description":"Current session status"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/concierge/alerts/{id}/agent-session":{"post":{"tags":["Kai Resolution Agent"],"summary":"Start agent session","description":"Initiates a new Kai resolution agent session for a signal. \nThe agent will analyze the signal and prepare to propose resolution actions.\nRequires create_agent_remediation permission and agentAI plan feature.\n","operationId":"startAgentSession","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID to create session for","schema":{"type":"integer"}}],"responses":{"201":{"description":"Agent session created","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/AgentSession"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or plan feature not available"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```
## Get agent session status
> Returns the current status and details of an agent session. Requires view\_agent\_remediation permission.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"AgentSessionDetail":{"allOf":[{"$ref":"#/components/schemas/AgentSession"},{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/AgentAnalysis"},"proposedActions":{"type":"array","items":{"$ref":"#/components/schemas/ProposedAction"}},"executionResults":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ExecutionResult"}},"error":{"type":"string","nullable":true,"description":"Error message if session failed"},"updatedAt":{"type":"string","format":"date-time"}}}]},"AgentSession":{"type":"object","required":["id","alertId","status","createdAt"],"properties":{"id":{"type":"integer","description":"Unique session identifier"},"alertId":{"type":"integer","description":"Associated signal ID"},"status":{"type":"string","enum":["started","analyzing","awaiting_confirmation","executing","completed","failed","cancelled"],"description":"Current session status"},"createdAt":{"type":"string","format":"date-time"}}},"AgentAnalysis":{"type":"object","description":"Kai's root cause analysis of the anomaly","properties":{"rootCause":{"type":"string","description":"Identified root cause of the issue"},"impact":{"type":"string","description":"Business impact assessment"},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"List of affected systems/services"},"entityLifecycleContext":{"type":"string","description":"Context about billing entity lifecycle (Usage → Rating → Billing → Invoice → Payment)"},"isAnomalyPattern":{"type":"boolean","description":"Whether this represents a systemic pattern vs isolated failure"},"patternDescription":{"type":"string","nullable":true,"description":"Description of the detected pattern if applicable"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Confidence level of the analysis"}}},"ProposedAction":{"type":"object","required":["id","actionType","description","isAutomated"],"properties":{"id":{"type":"string","description":"Unique action identifier"},"actionType":{"type":"string","enum":["reprocess_usage_batch","replay_usage_events","recalculate_charges","retry_billing_run","backfill_invoices","retry_payment_batch","pause_payment_runs","sync_subscription_state","repair_entitlements","rollback_configuration","manual_review","contact_support"],"description":"Type of resolution action"},"description":{"type":"string","description":"Human-readable description of what this action does"},"isAutomated":{"type":"boolean","description":"Whether Kai can execute this automatically (true) or requires manual intervention (false)"},"targetSystem":{"type":"string","description":"Target billing/payment system"},"targetEntities":{"type":"array","items":{"type":"string"},"description":"Entity IDs this action will affect"},"expectedOutcome":{"type":"string","description":"Expected result of executing this action"},"risk":{"type":"string","enum":["low","medium","high"],"description":"Risk level of this action"},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"description":{"type":"string"},"apiCall":{"type":"string","nullable":true}}},"description":"Detailed steps for this action"}}},"ExecutionResult":{"type":"object","required":["actionId","success"],"properties":{"actionId":{"type":"string","description":"ID of the executed action"},"success":{"type":"boolean","description":"Whether the action executed successfully"},"response":{"type":"object","nullable":true,"description":"API response from the target system"},"error":{"type":"string","nullable":true,"description":"Error message if execution failed"},"executedAt":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Execution duration in milliseconds"}}}}},"paths":{"/concierge/agent-sessions/{id}":{"get":{"tags":["Kai Resolution Agent"],"summary":"Get agent session status","description":"Returns the current status and details of an agent session. Requires view_agent_remediation permission.","operationId":"getAgentSession","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Agent session details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionDetail"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```
## Generate action proposals
> Triggers Kai to analyze the signal and generate proposed resolution actions.\
> The agent performs root cause analysis and identifies systemic issues rather than isolated failures.\
> Actions are categorized as automated (Kai can execute) or manual (requires user intervention).\
> Requires create\_agent\_remediation permission and agentAI plan feature.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"AgentAnalysis":{"type":"object","description":"Kai's root cause analysis of the anomaly","properties":{"rootCause":{"type":"string","description":"Identified root cause of the issue"},"impact":{"type":"string","description":"Business impact assessment"},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"List of affected systems/services"},"entityLifecycleContext":{"type":"string","description":"Context about billing entity lifecycle (Usage → Rating → Billing → Invoice → Payment)"},"isAnomalyPattern":{"type":"boolean","description":"Whether this represents a systemic pattern vs isolated failure"},"patternDescription":{"type":"string","nullable":true,"description":"Description of the detected pattern if applicable"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Confidence level of the analysis"}}},"ProposedAction":{"type":"object","required":["id","actionType","description","isAutomated"],"properties":{"id":{"type":"string","description":"Unique action identifier"},"actionType":{"type":"string","enum":["reprocess_usage_batch","replay_usage_events","recalculate_charges","retry_billing_run","backfill_invoices","retry_payment_batch","pause_payment_runs","sync_subscription_state","repair_entitlements","rollback_configuration","manual_review","contact_support"],"description":"Type of resolution action"},"description":{"type":"string","description":"Human-readable description of what this action does"},"isAutomated":{"type":"boolean","description":"Whether Kai can execute this automatically (true) or requires manual intervention (false)"},"targetSystem":{"type":"string","description":"Target billing/payment system"},"targetEntities":{"type":"array","items":{"type":"string"},"description":"Entity IDs this action will affect"},"expectedOutcome":{"type":"string","description":"Expected result of executing this action"},"risk":{"type":"string","enum":["low","medium","high"],"description":"Risk level of this action"},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"description":{"type":"string"},"apiCall":{"type":"string","nullable":true}}},"description":"Detailed steps for this action"}}}}},"paths":{"/concierge/agent-sessions/{id}/propose":{"post":{"tags":["Kai Resolution Agent"],"summary":"Generate action proposals","description":"Triggers Kai to analyze the signal and generate proposed resolution actions.\nThe agent performs root cause analysis and identifies systemic issues rather than isolated failures.\nActions are categorized as automated (Kai can execute) or manual (requires user intervention).\nRequires create_agent_remediation permission and agentAI plan feature.\n","operationId":"proposeActions","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Actions proposed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["awaiting_confirmation"]},"alertId":{"type":"integer"},"analysis":{"$ref":"#/components/schemas/AgentAnalysis"},"proposedActions":{"type":"array","items":{"$ref":"#/components/schemas/ProposedAction"}}}}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```
## Execute approved actions
> Executes the specified resolution actions that the user has approved.\
> The agent will make API calls to the relevant billing/payment systems and report results.\
> Requires execute\_agent\_remediation permission and agentAI plan feature.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ExecutionResult":{"type":"object","required":["actionId","success"],"properties":{"actionId":{"type":"string","description":"ID of the executed action"},"success":{"type":"boolean","description":"Whether the action executed successfully"},"response":{"type":"object","nullable":true,"description":"API response from the target system"},"error":{"type":"string","nullable":true,"description":"Error message if execution failed"},"executedAt":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Execution duration in milliseconds"}}},"AgentSessionDetail":{"allOf":[{"$ref":"#/components/schemas/AgentSession"},{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/AgentAnalysis"},"proposedActions":{"type":"array","items":{"$ref":"#/components/schemas/ProposedAction"}},"executionResults":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ExecutionResult"}},"error":{"type":"string","nullable":true,"description":"Error message if session failed"},"updatedAt":{"type":"string","format":"date-time"}}}]},"AgentSession":{"type":"object","required":["id","alertId","status","createdAt"],"properties":{"id":{"type":"integer","description":"Unique session identifier"},"alertId":{"type":"integer","description":"Associated signal ID"},"status":{"type":"string","enum":["started","analyzing","awaiting_confirmation","executing","completed","failed","cancelled"],"description":"Current session status"},"createdAt":{"type":"string","format":"date-time"}}},"AgentAnalysis":{"type":"object","description":"Kai's root cause analysis of the anomaly","properties":{"rootCause":{"type":"string","description":"Identified root cause of the issue"},"impact":{"type":"string","description":"Business impact assessment"},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"List of affected systems/services"},"entityLifecycleContext":{"type":"string","description":"Context about billing entity lifecycle (Usage → Rating → Billing → Invoice → Payment)"},"isAnomalyPattern":{"type":"boolean","description":"Whether this represents a systemic pattern vs isolated failure"},"patternDescription":{"type":"string","nullable":true,"description":"Description of the detected pattern if applicable"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Confidence level of the analysis"}}},"ProposedAction":{"type":"object","required":["id","actionType","description","isAutomated"],"properties":{"id":{"type":"string","description":"Unique action identifier"},"actionType":{"type":"string","enum":["reprocess_usage_batch","replay_usage_events","recalculate_charges","retry_billing_run","backfill_invoices","retry_payment_batch","pause_payment_runs","sync_subscription_state","repair_entitlements","rollback_configuration","manual_review","contact_support"],"description":"Type of resolution action"},"description":{"type":"string","description":"Human-readable description of what this action does"},"isAutomated":{"type":"boolean","description":"Whether Kai can execute this automatically (true) or requires manual intervention (false)"},"targetSystem":{"type":"string","description":"Target billing/payment system"},"targetEntities":{"type":"array","items":{"type":"string"},"description":"Entity IDs this action will affect"},"expectedOutcome":{"type":"string","description":"Expected result of executing this action"},"risk":{"type":"string","enum":["low","medium","high"],"description":"Risk level of this action"},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"description":{"type":"string"},"apiCall":{"type":"string","nullable":true}}},"description":"Detailed steps for this action"}}}}},"paths":{"/concierge/agent-sessions/{id}/execute":{"post":{"tags":["Kai Resolution Agent"],"summary":"Execute approved actions","description":"Executes the specified resolution actions that the user has approved.\nThe agent will make API calls to the relevant billing/payment systems and report results.\nRequires execute_agent_remediation permission and agentAI plan feature.\n","operationId":"executeActions","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["actionIds"],"properties":{"actionIds":{"type":"array","items":{"type":"string"},"description":"IDs of approved actions to execute"}}}}}},"responses":{"200":{"description":"Actions executed","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ExecutionResult"}},"session":{"$ref":"#/components/schemas/AgentSessionDetail"}}}}}},"400":{"description":"actionIds array required"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```
## Cancel agent session
> Cancels an active agent session. Requires create\_agent\_remediation permission.
```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/agent-sessions/{id}/cancel":{"post":{"tags":["Kai Resolution Agent"],"summary":"Cancel agent session","description":"Cancels an active agent session. Requires create_agent_remediation permission.","operationId":"cancelAgentSession","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Session cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```
# Support Home
What can we help you find?
Browse the topics below or use the Kaana assistant to ask anything you need help with.
Ask Kaana AI Contact support
| | |
|---|
| Troubleshooting | Find solutions to common issues and guidance for resolving problems. | Troubleshooting |
| Known Issues | View active issues, limitations, and current workarounds. | Known Issues |
| Support Processes | Learn how to contact support, submit requests, and track issues. | Support Processes |
| User Management | Manage users, roles, access, and account settings. | User Management |
| Security & Privacy | Review how Kaana handles security, data protection, and privacy. | Security & Privacy |
# Common Issues & Solutions
Quick solutions for common problems you might encounter.
## Login Issues
### "Invalid email or password"
{% stepper %}
{% step %}
Check for typos in your email.
{% endstep %}
{% step %}
Make sure Caps Lock is off.
{% endstep %}
{% step %}
Try resetting your password.
{% endstep %}
{% step %}
Clear browser cookies and try again.
{% endstep %}
{% endstepper %}
### Account locked
**Cause:** Too many failed login attempts
{% stepper %}
{% step %}
Wait 15 minutes.
{% endstep %}
{% step %}
Try logging in again.
{% endstep %}
{% step %}
Use the password reset if needed.
{% endstep %}
{% endstepper %}
### Reset email not received
{% stepper %}
{% step %}
Check your spam/junk folder.
{% endstep %}
{% step %}
Make sure you used the correct email.
{% endstep %}
{% step %}
Try requesting another reset.
{% endstep %}
{% step %}
Contact your administrator.
{% endstep %}
{% endstepper %}
## Navigation Issues
### Missing menu items
**Cause:** Your role doesn't have access
{% stepper %}
{% step %}
Check your role in Settings > Profile.
{% endstep %}
{% step %}
Ask your administrator for access.
{% endstep %}
{% step %}
Verify the feature is enabled for your organization.
{% endstep %}
{% endstepper %}
### "Access Denied" error
**Cause:** Insufficient permissions
{% stepper %}
{% step %}
Verify you have permission for that action.
{% endstep %}
{% step %}
Check if you're accessing the correct tenant.
{% endstep %}
{% step %}
Contact your administrator.
{% endstep %}
{% endstepper %}
## Data Issues
### Changes not saving
{% stepper %}
{% step %}
Check your internet connection.
{% endstep %}
{% step %}
Look for error messages.
{% endstep %}
{% step %}
Refresh the page.
{% endstep %}
{% step %}
Try again.
{% endstep %}
{% step %}
Contact support if issue persists.
{% endstep %}
{% endstepper %}
### Data not loading
{% stepper %}
{% step %}
Refresh the page.
{% endstep %}
{% step %}
Clear browser cache.
{% endstep %}
{% step %}
Try a different browser.
{% endstep %}
{% step %}
Check internet connection.
{% endstep %}
{% endstepper %}
### Search not finding items
{% stepper %}
{% step %}
Check spelling.
{% endstep %}
{% step %}
Try partial matches.
{% endstep %}
{% step %}
Clear filters.
{% endstep %}
{% step %}
Search in the correct section.
{% endstep %}
{% endstepper %}
## Performance Issues
### Slow page loads
{% stepper %}
{% step %}
Check internet speed.
{% endstep %}
{% step %}
Clear browser cache.
{% endstep %}
{% step %}
Close unnecessary tabs.
{% endstep %}
{% step %}
Try a different browser.
{% endstep %}
{% step %}
Disable browser extensions.
{% endstep %}
{% endstepper %}
### Page not responding
{% stepper %}
{% step %}
Wait a moment for processing.
{% endstep %}
{% step %}
Refresh the page.
{% endstep %}
{% step %}
Clear cache and cookies.
{% endstep %}
{% step %}
Try incognito/private mode.
{% endstep %}
{% endstepper %}
## File Upload Issues
### Upload fails
**Possible causes:**
* File too large (max 10MB)
* Unsupported file type
* Network timeout
{% stepper %}
{% step %}
Check file size.
{% endstep %}
{% step %}
Verify file type is supported.
{% endstep %}
{% step %}
Try a smaller file.
{% endstep %}
{% step %}
Check internet connection.
{% endstep %}
{% endstepper %}
### Document won't open
{% stepper %}
{% step %}
Download and open locally.
{% endstep %}
{% step %}
Check file isn't corrupted.
{% endstep %}
{% step %}
Try a different browser.
{% endstep %}
{% step %}
Re-upload the file.
{% endstep %}
{% endstepper %}
## Integration Issues
### Integration not connecting
{% stepper %}
{% step %}
Check your credentials.
{% endstep %}
{% step %}
Verify the service is accessible.
{% endstep %}
{% step %}
Try disconnecting and reconnecting.
{% endstep %}
{% step %}
Check for error messages.
{% endstep %}
{% endstepper %}
### Data not syncing
{% stepper %}
{% step %}
Check integration status.
{% endstep %}
{% step %}
Look for error indicators.
{% endstep %}
{% step %}
Verify permissions in the connected service.
{% endstep %}
{% step %}
Refresh the connection.
{% endstep %}
{% endstepper %}
### Webhook not triggering
{% stepper %}
{% step %}
Verify webhook URL is correct.
{% endstep %}
{% step %}
Check endpoint is accessible.
{% endstep %}
{% step %}
Review event configuration.
{% endstep %}
{% step %}
Test with the Test button.
{% endstep %}
{% endstepper %}
## Email/Notification Issues
### Not receiving notifications
{% stepper %}
{% step %}
Check Settings > Notifications.
{% endstep %}
{% step %}
Verify email address is correct.
{% endstep %}
{% step %}
Check spam/junk folder.
{% endstep %}
{% step %}
Ensure notifications are enabled.
{% endstep %}
{% endstepper %}
### Getting too many notifications
{% stepper %}
{% step %}
Go to Settings > Notifications.
{% endstep %}
{% step %}
Adjust notification preferences.
{% endstep %}
{% step %}
Turn off non-essential alerts.
{% endstep %}
{% endstepper %}
## Mobile/Browser Issues
### Display problems
{% stepper %}
{% step %}
Use a supported browser (Chrome, Firefox, Safari, Edge).
{% endstep %}
{% step %}
Update to the latest browser version.
{% endstep %}
{% step %}
Clear cache and cookies.
{% endstep %}
{% step %}
Disable ad blockers.
{% endstep %}
{% endstepper %}
### Features not working
{% stepper %}
{% step %}
Enable JavaScript.
{% endstep %}
{% step %}
Allow cookies for the site.
{% endstep %}
{% step %}
Disable conflicting extensions.
{% endstep %}
{% step %}
Try incognito mode.
{% endstep %}
{% endstepper %}
## When to Contact Support
Contact support if:
* You've tried the solutions above
* You're seeing error messages repeatedly
* Data appears corrupted
* You need account-level changes
Include in your report:
* What you were trying to do
* What happened instead
* Any error messages
* Steps to reproduce
* Screenshots if possible
# Frequently Asked Questions
Find answers to common questions about using Kaana.
Updated over a month ago
## Account & Login
I forgot my password. How do I reset it?
* Go to the login page
* Click "Forgot Password"
* Enter your email address
* Check your email for a reset link
* Click the link and create a new password
Why can't I log in?
Common reasons:
* **Incorrect email/password** — Double-check for typos
* **Account locked** — Wait 15 minutes after multiple failed attempts
* **Account deactivated** — Contact your administrator
How do I change my email address?
* Go to Settings > Profile
* Update the email field
* Verify the new email address
* Your login will update
## Navigation & Features
Why can't I see certain menu items?
Your role determines what you can access. If you need access to a feature, contact your administrator to adjust your permissions.
How do I customize my navigation?
* Go to Settings > Preferences
* Drag and drop menu items to reorder
* Your layout is saved automatically
Where did my project go?
Check if:
* The project was deleted (check with owner)
* You were removed from the project
* Filters are hiding it (clear all filters)
## Projects & Tasks
How do I create a new project?
* Click "+ New Project" from Projects page or dashboard
* Enter the project name and details
* Click "Create"
How do I assign a task to someone?
* Open the task
* Click the "Assignee" field
* Select the person
* They'll be notified
How do I mark a task as complete?
* Open the task
* Change the status to "Completed"
* Or click the checkbox in the task list
Why can't I edit a project?
You may not have edit permissions. Check with:
* The project owner
* Your administrator
## Documents
What file types can I upload?
Supported formats include:
* PDF documents
* Word documents (.docx)
* Excel spreadsheets (.xlsx)
* Images (PNG, JPG)
* And more
How large can files be?
Maximum file size is 10MB. For larger files, consider:
* Compressing the file
* Splitting into multiple files
* Linking to external storage
How do I download a document?
* Open the document
* Click "Download"
* The file saves to your computer
## Teams & Permissions
How do I add someone to my team?
If you're an admin:
* Go to Settings > Users
* Click "+ Invite User"
* Enter their email and role
* Send the invitation
What are the different roles?
| Role | Access |
| ------ | ----------------------- |
| Owner | Full access, billing |
| Admin | Full access, no billing |
| Member | Standard access |
| Guest | Read-only |
How do I change someone's role?
If you're an admin:
* Go to Settings > Users
* Find the user
* Select a new role
* Save
## Billing
How do I change my plan?
* Go to Settings > Billing
* Click "Change Plan"
* Select new plan
* Confirm change
How do I add more users?
* Go to Settings > Billing
* Click "Add Seats"
* Enter number of seats
* Confirm
Where are my invoices?
* Go to Settings > Billing
* Click "Payment History"
* Download any invoice
## Integrations
How do I connect Slack?
* Go to Settings > Integrations
* Find Slack
* Click "Connect"
* Authorize in Slack
Why is my integration not syncing?
Try:
1. Check connection status in Integrations
2. Refresh the connection
3. Re-authorize if needed
4. Check for error messages
## Performance
The app is running slowly. What can I do?
* Clear your browser cache
* Try a different browser
* Close unused tabs
* Check your internet connection
Data isn't updating. What should I do?
* Refresh the page
* Clear browser cache
* Log out and back in
* Report if issue persists
## Getting More Help
How do I contact support?
* Use the Help menu in the app
* Email support from your Settings page
* Check the Help Center for guides
How do I report a bug?
* Note what happened and steps to reproduce
* Take a screenshot if possible
* Contact support with details
How do I request a feature?
Contact support or your account manager with:
* Description of the feature
* Why it would help you
* How you’d use it
# Unable to Login to Kaana
Below are typical situations users might face:
1. **Forgetting Login Credentials:** Users may forget their username and password and require assistance in recovering them.
2. **Billing System Integration Changes:** There could be instances where the username and password for billing system integration have altered, expired, or the account is deactivated. Users will need to update their details accordingly.
3. **Deletion from Kaana:** If a user's account is deactivated in the billing system, their Kaana account will also be removed. This ensures data consistency.
4. **Single Sign-On Issues:** Users employing Single Sign-On (e.g., logging in with Salesforce, Google, or Facebook) may encounter issues if their account is deactivated or deleted in the source application. It's vital to verify the user's status in the source application and ensure no changes to their username or password.
The most common scenario is the deactivation of the integration user, established in Kaana’s administrative section. If this occurs, it's advisable to update the integration user's information or reactivate their account.
Should you encounter any of these situations, please adhere to the recommended steps for swift resolution.
\
# Contact Support
The best way to get day-to-day support is to submit an email to our customer success team. It allows us to track progress and ensure there is a single location for communication, making sure nothing is ever overlooked.
**Email: **
Please note that tickets sent via emails will not have a priority assigned to them and might not be prioritized accordingly.
**Telephone Support:**
We’re available for technical emergencies 24x7x365 by phone. If you are experiencing an Urgent (P0) or High (P1) response time outside business hours, please use our telephone support. Call us at:
* US: +1 858-261-7778
**2026 US Public Holidays:**
New Year's Day, Thursday, January 01
Good Friday, Friday, April 3, 2026
Memorial Day, Monday, May 25
Independence Day, Friday, July 03 \*\*
Labor Day, Monday, September 07
Veterans Day, Wednesday, November 11
Thanksgiving Day, Thursday, November 26
Christmas Day, Friday, December 25
\*\*If a holiday falls on a Saturday the preceding Friday will be treated as a holiday.
\
# User Management
Administrators can manage user accounts for their organization.
Updated over a month ago
## Accessing User Management
{% stepper %}
{% step %}
Go to **Settings**
{% endstep %}
{% step %}
Select **Users**
{% endstep %}
{% endstepper %}
## Viewing Users
### User List
See all users in your organization:
* Name and email
* Role
* Status (active/inactive)
* Last login
### Filtering
Filter users by:
* **Role** — Admin, Member, Guest
* **Status** — Active, inactive
* **Search** — Name or email
## Adding Users
### Invite a New User
{% stepper %}
{% step %}
Go to **Settings** > **Users**
{% endstep %}
{% step %}
Click **+ Invite User**
{% endstep %}
{% step %}
Enter their details:
* **Email** — Their email address
* **Name** — Full name
* **Role** — Select appropriate role
{% endstep %}
{% step %}
Click **Send Invite**
{% endstep %}
{% endstepper %}
### What Happens Next
{% stepper %}
{% step %}
User receives an email invitation
{% endstep %}
{% step %}
They click the link to set up their account
{% endstep %}
{% step %}
They create a password
{% endstep %}
{% step %}
They can start using Kaana
{% endstep %}
{% endstepper %}
## Pending Invitations
View invitations that haven't been accepted:
* See pending invites
* Resend if needed
* Cancel invitations
## Editing Users
### Update User Details
{% stepper %}
{% step %}
Find the user in the list
{% endstep %}
{% step %}
Click their name
{% endstep %}
{% step %}
Edit details:
* Name
* Role
* Status
{% endstep %}
{% step %}
Save changes
{% endstep %}
{% endstepper %}
### Change User Role
{% stepper %}
{% step %}
Open the user
{% endstep %}
{% step %}
Select new role from dropdown
{% endstep %}
{% step %}
Save
{% endstep %}
{% endstepper %}
Role changes take effect immediately.
## Deactivating Users
When someone leaves or no longer needs access:
{% stepper %}
{% step %}
Find the user
{% endstep %}
{% step %}
Click **Deactivate**
{% endstep %}
{% step %}
Confirm
{% endstep %}
{% endstepper %}
Deactivated users:
* Cannot log in
* Don't appear in active lists
* Their data is preserved
* Can be reactivated later
## Reactivating Users
Restore access to a deactivated user:
{% stepper %}
{% step %}
Filter to show inactive users
{% endstep %}
{% step %}
Find the user
{% endstep %}
{% step %}
Click **Reactivate**
{% endstep %}
{% step %}
They can log in again
{% endstep %}
{% endstepper %}
## Deleting Users
Permanently remove a user:
{% stepper %}
{% step %}
Open the user
{% endstep %}
{% step %}
Click **Delete**
{% endstep %}
{% step %}
Confirm deletion
{% endstep %}
{% endstepper %}
Warning: This permanently removes the user. Their data may be reassigned or deleted.
## User Roles
Assign appropriate roles:
| Role | Access Level |
| ---------- | ------------------------- |
| **Admin** | Full access, manage users |
| **Member** | Standard access |
| **Guest** | Read-only access |
See [Roles & Permissions](https://replit.com/t/kaana/repls/geraldwsotoka-12-19#help/team-permissions/roles.md) for details.
## Bulk Operations
Manage multiple users:
{% stepper %}
{% step %}
Select users using checkboxes
{% endstep %}
{% step %}
Choose an action:
* Change role
* Deactivate
* Send reminder email
{% endstep %}
{% step %}
Apply to all selected
{% endstep %}
{% endstepper %}
## User Activity
View user activity:
* Last login date
* Projects they own
* Tasks assigned
* Recent actions
## Best Practices
### Regular Review
* Audit users periodically
* Remove inactive accounts
* Update roles as needed
### Onboarding
* Use appropriate roles for new users
* Provide training resources
* Set up initial project access
### Offboarding
* Deactivate promptly when people leave
* Transfer ownership of their items
* Review what they owned
# Roles & Permissions
Understand and manage roles within your organization.
### Understanding Roles
Roles determine what users can see and do in Kaana. Each user has one role.
### Standard Roles
#### Owner
The highest level of access:
* All administrative permissions
* Billing and subscription management
* Can manage other admins
* Full access to all features
#### Admin
Administrative access:
* Create and manage all projects
* Manage users (except owners)
* Configure settings
* Access all reports
* Cannot manage billing
#### Member
Standard team access:
* View projects they're assigned to
* Create and edit tasks
* Upload documents
* Log activities
* Limited settings access
#### Guest
Read-only access:
* View assigned projects
* View documents
* Cannot create or edit
* Limited navigation
### Permission Categories
Permissions are grouped by feature.
#### Project Permissions
* View projects
* Create projects
* Edit own projects
* Edit all projects
* Delete projects
#### Document Permissions
* View documents
* Upload documents
* Edit own documents
* Edit all documents
#### Activity Permissions
* View activities
* Create activities
* Edit own activities
* Edit all activities
#### Issue Permissions
* View issues
* Create issues
* Edit own issues
* Edit all issues
#### Administrative Permissions
* Manage users
* Manage roles
* Configure integrations
* Access reports
### Custom Roles
Administrators can create custom roles.
{% stepper %}
{% step %}
### Create a Custom Role
Go to **Settings** > **Roles**, click **+ New Role**, then enter:
* **Role Name** — e.g., "Project Manager"
* **Description** — What this role is for
Select permissions for each category and click **Create**.
{% endstep %}
{% step %}
### Edit a Custom Role
* Find the role in the list
* Click to open
* Modify permissions
* Save changes
Changes affect all users with that role.
{% endstep %}
{% step %}
### Delete a Custom Role
* Open the role
* Click **Delete**
* Choose where to move affected users
* Confirm
Note: Standard roles cannot be deleted.
{% endstep %}
{% endstepper %}
### Assigning Roles
{% stepper %}
{% step %}
### Set User Role
* Go to **Settings** > **Users**
* Open the user
* Select role from dropdown
* Save
{% endstep %}
{% step %}
### Multiple Role Assignment
Some organizations allow users to have different roles on different projects. Contact your administrator for details.
{% endstep %}
{% endstepper %}
### Ownership-Based Permissions
Some permissions check ownership:
* "Own" items — Users can only modify content they created
* "All" items — Users can modify any content
Example: A Member with "Edit own projects" can edit projects they created but not others.
### Permission Inheritance
Higher roles include lower role permissions:
* Owner > Admin > Member > Guest
An Admin has all Member permissions plus additional access.
### Troubleshooting Access
"Access Denied" Message
This means your role doesn't have permission for that action. Contact your administrator if you need access.
Missing Menu Items
Navigation only shows items you can access. Missing items may indicate:
* Your role doesn't have access
* The feature is disabled
Contact admin for clarification.
Can't Find a Feature
Check if:
* Your role has access
* The feature is enabled for your organization
* You're looking in the right section
### Best Practices
#### Role Assignment
* Assign minimum necessary access
* Review roles during onboarding
* Update as responsibilities change
#### Custom Roles
* Create roles for common job functions
* Name roles clearly
* Document role purposes
#### Regular Review
* Audit permissions periodically
* Remove unnecessary access
* Update as features change
# User Profile Settings
Manage your personal account settings and preferences.
### Accessing Profile Settings
{% stepper %}
{% step %}
Click your avatar or name in the top right.
{% endstep %}
{% step %}
Select **Profile** or **Settings**.
{% endstep %}
{% step %}
Navigate to the Profile section.
{% endstep %}
{% endstepper %}
### Personal Information
#### Update Your Profile
Edit your personal details:
* **Full Name** — Your display name
* **Email** — Your login email
* **Phone** — Contact number
* **Title** — Job title
* **Department** — Your department
#### Profile Picture
{% stepper %}
{% step %}
Click the avatar placeholder.
{% endstep %}
{% step %}
Upload an image.
{% endstep %}
{% step %}
Crop if needed.
{% endstep %}
{% step %}
Save.
{% endstep %}
{% endstepper %}
### Account Settings
#### Email Address
Your email is used for:
* Login
* Notifications
* Password recovery
To change your email:
{% stepper %}
{% step %}
Go to Profile Settings.
{% endstep %}
{% step %}
Update the email field.
{% endstep %}
{% step %}
Verify the new email.
{% endstep %}
{% step %}
Your login updates.
{% endstep %}
{% endstepper %}
#### Password
To change your password:
{% stepper %}
{% step %}
Go to Profile Settings.
{% endstep %}
{% step %}
Click **Change Password**.
{% endstep %}
{% step %}
Enter current password.
{% endstep %}
{% step %}
Enter new password.
{% endstep %}
{% step %}
Confirm new password.
{% endstep %}
{% step %}
Click **Save**.
{% endstep %}
{% endstepper %}
Password requirements:
* Minimum 8 characters
* Mix of letters, numbers, symbols
* Different from previous passwords
### Preferences
#### Notification Preferences
Control what notifications you receive:
* **Email notifications** — Get updates via email
* **Task assignments** — When you're assigned tasks
* **Mentions** — When someone @mentions you
* **Due date reminders** — Upcoming deadlines
* **Project updates** — Changes to your projects
#### Navigation Order
Customize your sidebar:
{% stepper %}
{% step %}
Go to Preferences.
{% endstep %}
{% step %}
Drag menu items to reorder.
{% endstep %}
{% step %}
Save your layout.
{% endstep %}
{% step %}
Navigation updates immediately.
{% endstep %}
{% endstepper %}
#### Display Settings
Adjust how information displays:
* **Date format** — MM/DD/YYYY or DD/MM/YYYY
* **Time zone** — Your local time zone
* **Theme** — Light or dark mode (if available)
### Activity History
View your account activity:
* Recent logins
* Actions taken
* Changes made
### Security
#### Two-Factor Authentication
If available, enable 2FA:
{% stepper %}
{% step %}
Go to Security settings.
{% endstep %}
{% step %}
Click **Enable 2FA**.
{% endstep %}
{% step %}
Follow setup instructions.
{% endstep %}
{% step %}
Save backup codes.
{% endstep %}
{% endstepper %}
#### Sessions
View and manage active sessions:
* See where you're logged in
* End sessions on other devices
* Log out everywhere
### Linked Accounts
If your organization uses single sign-on:
* View linked providers
* Manage connections
* Set primary login method
### Deleting Your Account
{% stepper %}
{% step %}
Contact your administrator.
{% endstep %}
{% step %}
They can deactivate your access.
{% endstep %}
{% step %}
Data may be retained per policy.
{% endstep %}
{% endstepper %}
# Security Overview
Kaana is built with security at its core. We protect your data using industry-standard practices and enterprise-grade infrastructure.
### Our Security Commitment
* Your data is encrypted at rest and in transit
* We never share your data with third parties
* Regular security audits and updates
* Compliant with industry standards
### Key Security Features
### Data Protection
| Feature | Description |
| ------------------------- | ------------------------------------- |
| **Encryption in Transit** | All data transmitted using TLS 1.3 |
| **Encryption at Rest** | Sensitive data encrypted with AES-256 |
| **Secure Authentication** | Industry-standard Auth0 integration |
| **Session Security** | HTTP-only cookies, secure sessions |
### Access Control
* **Role-Based Permissions** — Users only access what they need
* **Multi-Tenant Isolation** — Your data is completely separate from other customers
* **Audit Logging** — Track who accessed what and when
### Infrastructure
* Hosted on secure, SOC 2 compliant infrastructure (AWS)
* Regular backups with point-in-time recovery
* Automatic security patches and updates
### Security Resources
* [Data Privacy](/support/security-and-privacy/data-privacy) — How we handle your data
* [AI Security](https://docs.kaana.com/ai-integrations/kaana-ai-kai/ai-security) — How AI features protect your information
* [Authentication Security](/support/security-and-privacy/authentication-security) — Login and access security
* [Compliance](/support/security-and-privacy/compliance-and-standards) — Standards and certifications
Reporting Security Issues
If you discover a security vulnerability, please contact us immediately. We take all reports seriously and will respond promptly.
Questions?
Have security questions? Contact our team and we'll be happy to provide more details about our security practices.
# Data Privacy
Learn how Kaana protects and handles your data.
## Your Data Ownership
**You own your data.** We are custodians, not owners. You can:
* Export your data at any time
* Request deletion of your data
* Control who has access
## What Data We Collect
### Account Data
* Email address and name
* Company/organization name
* Login activity
### Application Data
* Projects, tasks, and documents you create
* Activities and comments
* Settings and preferences
### Usage Data
* Feature usage (to improve the product)
* Error logs (to fix issues)
## How We Protect Your Data
### Encryption
| Data Type | Protection |
| ---------------- | ----------------------------------------------- |
| Passwords | Hashed with scrypt (never stored in plain text) |
| Sensitive fields | Encrypted with AES-256-CBC |
| Data in transit | TLS 1.3 encryption |
| Backups | Encrypted at rest |
### Access Controls
* Only authorized personnel can access production systems
* All access is logged and monitored
* Regular access reviews
### Data Isolation
Your data is isolated from other customers:
* Tenant-based data separation
* Database-level access controls
* No cross-tenant data access
## Data Retention
### Active Accounts
* Data retained as long as your account is active
* Regular backups maintained for recovery
### Deleted Data
* Deleted items removed from active database
* Backups retained for 30 days
* After 30 days, data is permanently removed
### Account Closure
* Request data export before closing
* Data deleted within 30 days of closure
* Confirmation provided upon completion
## Data Location
Your data is stored in secure data centers with:
* Physical security controls
* Environmental protections
* Redundant systems
## Third-Party Services
We use trusted third-party services:
| Service | Purpose | Data Shared |
| -------- | -------------- | ------------------------------------- |
| Auth0 | Authentication | Email, name |
| Stripe | Payments | Billing info |
| SendGrid | Email delivery | Email address |
| OpenAI | AI features | Content you analyze (see AI Security) |
All third parties are vetted for security compliance.
## Your Rights
You have the right to:
* **Access** — Request a copy of your data
* **Correction** — Update inaccurate information
* **Deletion** — Request data removal
* **Export** — Download your data
* **Restrict** — Limit how we use your data
Contact us to exercise these rights.
## Data Breach Response
{% stepper %}
{% step %}
### Investigate
We will investigate immediately.
{% endstep %}
{% step %}
### Notify
Affected users will be notified promptly.
{% endstep %}
{% step %}
### Prevent Recurrence
Steps taken to prevent recurrence.
{% endstep %}
{% step %}
### Regulatory Notification
Regulatory authorities notified as required.
{% endstep %}
{% endstepper %}
# Authentication Security
How Kaana keeps your account secure.
### Login Security
#### Secure Authentication
Kaana uses Auth0, an industry-leading authentication platform:
* Enterprise-grade security
* Regular security audits
* Compliance certifications
#### Password Requirements
Strong passwords are required:
* Minimum 8 characters
* Mix of letters, numbers, and symbols recommended
* Common passwords blocked
* Breach detection (warns if password found in data breaches)
#### Password Storage
Your password is never stored in plain text:
* Hashed using secure algorithms
* Salted to prevent rainbow table attacks
* We cannot see or retrieve your password
### Session Security
#### How Sessions Work
{% stepper %}
{% step %}
### Secure session creation
When you log in, a secure session is created.
{% endstep %}
{% step %}
### HTTP-only cookie
An HTTP-only cookie is set (not accessible to JavaScript).
{% endstep %}
{% step %}
### Session validation
Session is validated on each request.
{% endstep %}
{% step %}
### Automatic timeout
Session will automatically time out after inactivity.
{% endstep %}
{% endstepper %}
#### Session Features
| Feature | Description |
| --------------------- | -------------------------------- |
| **HTTP-Only Cookies** | Prevents XSS attacks |
| **Secure Flag** | Only sent over HTTPS |
| **Session Timeout** | Auto-logout after inactivity |
| **Single Session** | Option to log out other sessions |
### Account Protection
#### Failed Login Protection
* Account temporarily locked after multiple failed attempts
* Prevents brute-force attacks
* Automatic unlock after cooldown period
#### Suspicious Activity
We monitor for:
* Unusual login locations
* Multiple failed attempts
* Abnormal access patterns
#### Email Verification
* Email addresses verified on signup
* Notifications for account changes
* Password reset requires email access
### Password Reset
#### Secure Reset Process
{% stepper %}
{% step %}
### Request reset
Request reset from the login page.
{% endstep %}
{% step %}
### Secure link
An email is sent with a secure link.
{% endstep %}
{% step %}
### Expiration
The link expires after a limited time.
{% endstep %}
{% step %}
### New password
You must create a new password.
{% endstep %}
{% step %}
### Invalidate sessions
All sessions are invalidated after reset.
{% endstep %}
{% endstepper %}
#### Tips for Safe Reset
* Only request resets from the official Kaana login page
* Check email sender is legitimate
* Never share reset links
* Use a strong new password
### Protecting Your Account
#### Best Practices
{% stepper %}
{% step %}
### Use a strong, unique password
* Don't reuse passwords from other sites
* Consider a password manager
{% endstep %}
{% step %}
### Keep your email secure
* Your email is used for password resets
* Secure your email account
{% endstep %}
{% step %}
### Log out on shared devices
* Always log out when using shared computers
* Don't save password in public browsers
{% endstep %}
{% step %}
### Watch for phishing
* Verify URLs before entering credentials
* We'll never ask for your password via email
{% endstep %}
{% endstepper %}
#### Signs of Compromise
Watch for:
* Login notifications you didn't initiate
* Password reset emails you didn't request
* Unfamiliar activity in your account
* Settings changes you didn't make
If you notice these, change your password immediately and contact support.
### Administrator Controls
#### User Management
* Invite and remove users
* Set role-based permissions
* Monitor user activity
#### Security Settings
* Enforce password policies
* Review access logs
* Manage API keys
#### Deactivating Users
* Immediately revoke access
* Block future login attempts
* Preserve data for audit
### Logging Out
#### How to Log Out
{% stepper %}
{% step %}
Click your profile menu.
{% endstep %}
{% step %}
Select "Log Out".
{% endstep %}
{% step %}
Session is terminated.
{% endstep %}
{% step %}
You are redirected to the login page.
{% endstep %}
{% endstepper %}
#### Automatic Logout
Sessions expire after a period of inactivity for security.
# Compliance & Standards
Kaana's commitment to security standards and regulatory compliance.
### Security Standards
#### Infrastructure Security
Our infrastructure follows industry best practices:
| Standard | Description |
| ----------- | ---------------------------------------------------- |
| **SOC 2** | Security, availability, and confidentiality controls |
| **TLS 1.3** | Latest encryption for data in transit |
| **AES-256** | Strong encryption for data at rest |
#### Application Security
* Regular security assessments
* Dependency vulnerability scanning
* Secure development practices
* Code review requirements
### Data Protection
#### Encryption
All sensitive data is protected:
* **In Transit** – TLS 1.3 encryption for all connections
* **At Rest** – AES-256 encryption for stored data
* **Backups** – Encrypted backup storage
#### Access Controls
* Role-based access control (RBAC)
* Principle of least privilege
* Regular access reviews
* Multi-tenant data isolation
## Privacy Compliance
#### General Practices
We follow privacy principles including:
* Data minimization (collect only what's needed)
* Purpose limitation (use data only as stated)
* Transparency (clear privacy policies)
* User rights (access, correction, deletion)
#### Your Rights
Depending on your location, you may have rights to:
* Know what data we collect
* Access your personal data
* Correct inaccurate data
* Delete your data
* Export your data
* Restrict processing
Contact us to exercise these rights.
### Business Continuity
#### Availability
* High-availability infrastructure
* Geographic redundancy
* Automatic failover
* Regular uptime monitoring
#### Disaster Recovery
* Regular automated backups
* Point-in-time recovery capability
* Tested recovery procedures
* Recovery time objectives defined
#### Data Backup
| Backup Type | Frequency | Retention |
| ----------- | ---------- | --------- |
| Database | Continuous | 30 days |
| Full backup | Daily | 30 days |
| Archive | Weekly | 90 days |
### Vendor Management
#### Third-Party Security
All vendors are evaluated for:
* Security certifications
* Data handling practices
* Compliance status
* Incident response capability
### Key Vendors
| Vendor | Purpose | Compliance |
| -------- | ------------------------------ | ---------------- |
| Auth0 | Authentication | SOC 2, ISO 27001 |
| Stripe | Payments | PCI DSS Level 1 |
| OpenAI | AI services | SOC 2 |
| SendGrid | Email | SOC 2 |
| AWS | Application Hosting & Services | SOC 2 |
### Incident Response
#### Our Process
{% stepper %}
{% step %}
**Detection**
Identify and confirm the incident.
{% endstep %}
{% step %}
**Containment**
Limit the impact.
{% endstep %}
{% step %}
**Investigation**
Determine cause and scope.
{% endstep %}
{% step %}
**Notification**
Inform affected parties.
{% endstep %}
{% step %}
**Remediation**
Fix the issue.
{% endstep %}
{% step %}
**Review**
Prevent future occurrences.
{% endstep %}
{% endstepper %}
#### Notification
We will notify you promptly if:
* Your data may have been compromised
* A security incident affects your account
* Action is required on your part
### Security Documentation
#### Available Upon Request
For enterprise customers, we can provide:
* Security questionnaire responses
* Detailed architecture documentation
* Compliance attestations
* Penetration test summaries
Contact your account manager for access.
#### Continuous Improvement
We continuously enhance our security:
* Regular security training for staff
* Ongoing vulnerability assessments
* Security tool updates
* Process improvements
### Questions?
Have compliance or security questions?
Contact our team for more information about our security practices.
---
[Next Page](/llms-full.txt/1)
