GPT Actions Integration

Create a custom GPT that can access and manage your Knowledge AI project through OpenAI's GPT Actions feature.

🚀 Overview

GPT Actions integration enables:

• Custom GPT Creation: Build a personalized GPT for your knowledge base
• Smart Search & Management: Intelligent content search and creation
• Relationship Analysis: Discover connections between your content
• Update-First Workflow: Efficient content management avoiding duplicates
• Project-Specific Access: Secure, project-scoped API access

🤖 GPT Capabilities

Your custom GPT will be able to:

• ✅ Search your knowledge base intelligently
• ✅ Create and update notes with validation
• ✅ Discover relationships between content
• ✅ Prevent duplicate content creation
• ✅ Browse and organize by folders
• ✅ Provide context-aware responses

📋 Prerequisites

• OpenAI ChatGPT Plus account
• Active Knowledge AI project
• Project API key
• Access to GPT Builder

⚙️ Setup Guide

Step 1: Get Your API Key

1. Navigate to your project's API Keys section in Knowledge AI
2. Generate a new API key for GPT Actions
3. Copy the API key - you'll need it in step 6

Step 2: Access GPT Builder

1. Go to ChatGPT GPT Builder
2. Click "Create a GPT"
3. Choose to start in "Configure" mode

Step 3: Configure Your GPT

Basic Information:

• Name: "My Knowledge Base" (or your preferred name)
• Description: "Access and manage my Knowledge AI knowledge base"
• Instructions: Customize how your GPT should behave

Step 4: Add Actions

1. In the "Configure" tab, scroll down to "Actions"
2. Click "Create new action"
3. You'll see the Actions configuration interface

Step 5: Import OpenAPI Schema

Copy and paste the following OpenAPI 3.1.1 schema:

{
  "openapi": "3.1.1",
  "info": {
    "title": "Knowledge AI - Smart Knowledge Management (REST)",
    "description": "REST-style access to knowledge management tools. Works for any project: documentation, research, business planning, creative writing. Features search-first workflow and update-over-create efficiency.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "YOUR_PROJECT_MCP_URL"
    }
  ],
  "paths": {
    "/notes/search/unified": {
      "post": {
        "operationId": "searchNotes",
        "summary": "MANDATORY FIRST STEP: Search existing content",
        "description": "Unified intelligent search to find existing content before creating anything new. Always use this first to avoid duplicates.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search query"
                  },
                  "mode": {
                    "type": "string",
                    "enum": ["auto", "keyword", "semantic", "graph"],
                    "default": "auto",
                    "description": "Search mode - auto selects best approach"
                  },
                  "intelligence_level": {
                    "type": "string",
                    "enum": ["basic", "enhanced"],
                    "default": "enhanced",
                    "description": "Level of AI analysis"
                  },
                  "limit": {
                    "type": "number",
                    "default": 20
                  },
                  "include_relationships": {
                    "type": "boolean",
                    "default": true,
                    "description": "Include relationship context"
                  },
                  "include_graph_context": {
                    "type": "boolean", 
                    "default": true,
                    "description": "Include graph connections"
                  },
                  "include_entity_analysis": {
                    "type": "boolean",
                    "default": true,
                    "description": "Include entity analysis"
                  },
                  "response_format": {
                    "type": "string",
                    "default": "unified",
                    "description": "Response format type"
                  }
                },
                "required": ["query"]
              }
            }
          }
        },
        "security": [{"ApiKeyAuth": []}]
      }
    },
    "/notes": {
      "get": {
        "operationId": "listNotes",
        "summary": "Browse existing content to avoid duplicates",
        "description": "List notes in project. Use before creating to check what already exists.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {"type": "number", "default": 20}
          },
          {
            "name": "virtual_folder",
            "in": "query", 
            "schema": {"type": "string"},
            "description": "Filter by folder (e.g., 'research', 'projects')"
          }
        ],
        "security": [{"ApiKeyAuth": []}]
      },
      "post": {
        "operationId": "createNote",
        "summary": "Create new content ONLY after searching confirms it doesn't exist",
        "description": "AVOID duplicates - always search first with searchNotes(). Only create if truly new content.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Content title (avoid # symbol)"
                  },
                  "content": {
                    "type": "string",
                    "description": "Content body (supports markdown)"
                  },
                  "virtual_folder": {
                    "type": "string", 
                    "description": "Folder path (e.g., 'research', 'processes', 'projects/client-work')"
                  },
                  "tags": {
                    "type": "array",
                    "items": {"type": "string"}
                  }
                },
                "required": ["title", "content"]
              }
            }
          }
        },
        "security": [{"ApiKeyAuth": []}]
      }
    },
    "/notes/{noteId}": {
      "get": {
        "operationId": "getNote",
        "summary": "Read existing content - ALWAYS use before updates",
        "description": "Essential step before any update operation. Read content to understand structure.",
        "parameters": [
          {
            "name": "noteId",
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "security": [{"ApiKeyAuth": []}]
      },
      "patch": {
        "operationId": "updateNote",
        "summary": "PREFERRED over creating - update existing content",
        "description": "Smart content updates with validation. Always prefer updating over creating new content.",
        "parameters": [
          {
            "name": "noteId", 
            "in": "path",
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "old_str": {
                    "type": "string",
                    "description": "Text to replace (for content edits)"
                  },
                  "new_str": {
                    "type": "string", 
                    "description": "Replacement text"
                  },
                  "title": {
                    "type": "string",
                    "description": "New title (for metadata updates)"
                  },
                  "tags": {
                    "type": "array",
                    "items": {"type": "string"}
                  },
                  "preview": {
                    "type": "boolean",
                    "default": false,
                    "description": "Preview changes without applying"
                  }
                }
              }
            }
          }
        },
        "security": [{"ApiKeyAuth": []}]
      }
    },
    "/graph/notes/{noteId}/connections": {
      "get": {
        "operationId": "getConnections",
        "summary": "Smart relationship analysis with AI suggestions",
        "description": "Get existing connections plus AI-suggested relationships for content discovery.",
        "parameters": [
          {
            "name": "noteId",
            "in": "path", 
            "required": true,
            "schema": {"type": "string"}
          }
        ],
        "security": [{"ApiKeyAuth": []}]
      }
    },
    "/graph/notes/{noteId}/links": {
      "post": {
        "operationId": "addConnection", 
        "summary": "Connect related content - search first to verify targets exist",
        "description": "Create connections between content. Use searchNotes() first to verify target exists.",
        "parameters": [
          {
            "name": "noteId",
            "in": "path",
            "required": true, 
            "schema": {"type": "string"}
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "target_note_id": {
                    "type": "string",
                    "description": "Target content ID"
                  },
                  "relationship_type": {
                    "type": "string",
                    "enum": ["related_to", "part_of", "similar_to", "feature_of"],
                    "default": "related_to"
                  }
                },
                "required": ["target_note_id"]
              }
            }
          }
        },
        "security": [{"ApiKeyAuth": []}]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your project-specific API key"
      }
    }
  }
}

Step 6: Configure Authentication

1. In the Actions configuration, set Authentication to "API Key"
2. Set the Authentication Type to "Custom"
3. Set the Header Name to: X-API-Key
4. Enter your API key from Step 1 in the API Key field

Step 7: Replace Server URL

In the schema you pasted, replace YOUR_PROJECT_MCP_URL with your actual project's MCP URL.

Step 8: Test Your GPT

1. Click "Test" in the GPT Builder
2. Try asking your GPT to search your knowledge base
3. Verify it can create and update notes

✅ Verification

Test your GPT with these commands:

"Search my knowledge base for authentication patterns"
"Show me all my notes about API design"
"Create a note about today's meeting with the client"
"Update the project roadmap with the new timeline"
"Find connections related to my deployment documentation"

🛠️ Advanced GPT Configuration

Custom Instructions

Enhance your GPT with specific instructions:

You are a knowledge management assistant for my personal/work knowledge base. 

Always:
1. Search existing content before creating new notes
2. Suggest updates to existing content rather than duplicates
3. Identify relationships between content
4. Use appropriate folders for organization
5. Maintain consistent formatting and style

When searching:
- Use semantic search for conceptual queries
- Try multiple search terms if first attempt yields few results
- Look for related content to suggest connections

When creating content:
- Use clear, descriptive titles
- Add relevant tags for discoverability
- Structure content with proper markdown formatting
- Link to related existing content when appropriate

Conversation Starters

Add helpful conversation starters:

• "Search my knowledge base for..."
• "Create a note about..."
• "Show me recent notes in..."
• "Find connections between..."
• "Update my note on..."

Knowledge Uploads

You can upload additional context files to help your GPT understand:

• Your project's documentation style guide
• Common terminology and acronyms
• Organizational structure preferences
• Content templates

🔧 Troubleshooting

Schema Import Issues

1. JSON Validation: Ensure the schema is valid JSON
2. URL Replacement: Verify you replaced the server URL placeholder
3. Copy/Paste: Make sure the entire schema was copied correctly

Authentication Problems

1. API Key Format: Ensure the API key is entered correctly
2. Header Name: Verify the header name is exactly X-API-Key
3. Key Permissions: Check the API key has proper project access
4. Key Expiry: Regenerate the API key if it's expired

GPT Not Working

1. Test Actions: Use the test feature in GPT Builder
2. Check Logs: Look for error messages in the Actions panel
3. API Connectivity: Test your API endpoint directly
4. Schema Validation: Verify the OpenAPI schema is correct

Limited Functionality

1. Missing Operations: Ensure all required endpoints are in the schema
2. Parameter Issues: Check request parameters match the API
3. Response Format: Verify response formats are correct
4. Security Configuration: Ensure authentication is properly configured

💡 Best Practices

Content Organization

• Consistent Naming: Use clear, consistent naming conventions
• Folder Structure: Organize content with logical folder hierarchies
• Tagging Strategy: Develop a consistent tagging system
• Regular Maintenance: Periodically review and organize content

Search Optimization

• Descriptive Titles: Use descriptive titles for better searchability
• Rich Content: Include detailed content for better semantic search
• Cross-References: Link related content together
• Regular Updates: Keep content current and accurate

GPT Interaction

• Clear Queries: Be specific in your search queries
• Feedback Loop: Tell the GPT when results are helpful or not
• Iterative Refinement: Build on previous searches to narrow results
• Context Preservation: Reference previous findings in follow-up queries

🚀 Advanced Features

Multi-Project Setup

Create separate GPTs for different projects:

1. Work Knowledge GPT: Connected to work project
2. Personal Knowledge GPT: Connected to personal project
3. Research GPT: Connected to research project

Custom Workflows

Design specific workflows for your GPT:

Daily Standup Workflow:
1. "Search for yesterday's accomplishments"
2. "Create today's goals note"
3. "Update project status"
4. "Identify blockers and dependencies"

Integration with Other Tools

Your GPT can work alongside:

• Project management tools
• Calendar applications
• Email systems
• Development workflows

📞 Support

Need help with GPT Actions?

• Email: feedback@knowledge-ai.app
• Documentation: docs.knowledge-ai.app
• GPT Actions Help: docs.knowledge-ai.app/integrations/gpt-actions

Common Solutions

"Actions not responding"

• Check API key is valid and active
• Verify server URL in schema is correct
• Test API endpoint independently

"Search returning no results"

• Try different search terms
• Check if content exists in your knowledge base
• Verify search parameters are correct

"Cannot create notes"

• Ensure API key has write permissions
• Check if required fields are provided
• Verify folder paths exist

---

Last updated: 2025-01-14