{
  "schema_version": "1.0",
  "name": "crowterminal",
  "display_name": "CrowTerminal - External Brain for AI Agents",
  "description": "Persistent memory for AI agents working with creators. Store 6 months of versioned history while your agent stores 10-50 lines.",
  "version": "2.2.0",
  "author": "CrowTerminal",
  "homepage": "https://crowterminal.com",
  "documentation": "https://crowterminal.com/llms.txt",
  "authentication": {
    "type": "bearer",
    "registration_url": "https://api.crowterminal.com/api/agent/register",
    "header": "Authorization",
    "prefix": "Bearer"
  },
  "base_url": "https://api.crowterminal.com/api/agent",
  "pricing": {
    "model": "free_beta",
    "note": "FREE during beta. BYOK model - you pay for your own LLM tokens."
  },
  "tools": [
    {
      "name": "get_memory",
      "description": "Read current skill/memory version for a creator. Returns comprehensive profile including niche, hook patterns, engagement data.",
      "method": "GET",
      "path": "/memory/{clientId}",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": {
            "type": "string",
            "description": "Creator identifier",
            "required": true
          }
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "version": { "type": "integer" },
          "skill": { "type": "object" }
        }
      }
    },
    {
      "name": "get_memory_versions",
      "description": "Read historical versions to see what changed over time. Useful for tracking learning evolution.",
      "method": "GET",
      "path": "/memory/{clientId}/versions",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": {
            "type": "string",
            "description": "Creator identifier",
            "required": true
          },
          "limit": {
            "type": "integer",
            "description": "Number of versions to return",
            "default": 20
          }
        }
      }
    },
    {
      "name": "get_memory_diff",
      "description": "Compare two versions to see what changed and why.",
      "method": "GET",
      "path": "/memory/{clientId}/diff",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "from": { "type": "integer", "description": "Starting version number", "required": true },
          "to": { "type": "integer", "description": "Ending version number", "required": true }
        }
      }
    },
    {
      "name": "get_memory_pattern",
      "description": "Track a field over time for trend analysis. See how engagement, hook performance, etc. evolved.",
      "method": "GET",
      "path": "/memory/{clientId}/pattern",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "field": { "type": "string", "description": "Field to track (e.g., avgEngagement)", "required": true },
          "versions": { "type": "integer", "description": "How many versions to analyze", "default": 10 }
        }
      }
    },
    {
      "name": "write_memory",
      "description": "Add new learning to creator's memory. Creates a new version automatically.",
      "method": "POST",
      "path": "/memory/{clientId}",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "updates": {
            "type": "array",
            "description": "Array of field updates",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "value": { "type": "any" }
              }
            },
            "required": true
          },
          "source": { "type": "string", "description": "Who's writing (e.g., agent:larry)", "required": true }
        }
      }
    },
    {
      "name": "validate_changes",
      "description": "⭐ IMPORTANT: Before updating your MD, check if the change contradicts historical data. Prevents repeating mistakes.",
      "method": "POST",
      "path": "/memory/{clientId}/validate",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "proposedChanges": {
            "type": "array",
            "description": "Changes you're about to make",
            "items": {
              "type": "object",
              "properties": {
                "field": { "type": "string" },
                "oldValue": { "type": "any" },
                "newValue": { "type": "any" }
              }
            },
            "required": true
          }
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "validation": { "type": "string", "enum": ["safe", "caution", "blocked"] },
          "warnings": { "type": "array" },
          "recommendations": { "type": "array" }
        }
      }
    },
    {
      "name": "engagement_analysis",
      "description": "⭐⭐ THE KILLER ENDPOINT: Send your current MD, get engagement correlation for each field. Tells you what configuration performed best historically.",
      "method": "POST",
      "path": "/memory/{clientId}/engagement-analysis",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "agentMd": {
            "type": "object",
            "description": "Your current learning file/MD as JSON",
            "required": true
          }
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "versionsAnalyzed": { "type": "integer" },
          "overallStats": {
            "type": "object",
            "properties": {
              "peakEngagement": { "type": "number" },
              "peakVersion": { "type": "integer" },
              "yourSimilarityToTop": { "type": "string" },
              "yourSimilarityToBottom": { "type": "string" }
            }
          },
          "fieldAnalysis": { "type": "array", "description": "Per-field recommendations with improvement percentages" },
          "recommendations": { "type": "array", "description": "Actionable changes to improve engagement" }
        }
      }
    },
    {
      "name": "compare_md",
      "description": "Compare your MD directly with our versioned history. See differences and what you're missing.",
      "method": "POST",
      "path": "/memory/{clientId}/compare-md",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "agentMd": {
            "type": "object",
            "description": "Your current MD as JSON",
            "required": true
          }
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "differences": { "type": "array" },
          "missingInAgent": { "type": "array" },
          "summary": { "type": "string" }
        }
      }
    },
    {
      "name": "byok_analyze",
      "description": "Send a prompt with your own LLM API key. We inject creator context, you pay for inference.",
      "method": "POST",
      "path": "/byok/analyze",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "description": "Creator for context (optional)" },
          "prompt": { "type": "string", "description": "Your question/prompt", "required": true },
          "llm": {
            "type": "object",
            "properties": {
              "provider": { "type": "string", "enum": ["anthropic", "openai"], "required": true },
              "apiKey": { "type": "string", "description": "Your LLM API key", "required": true },
              "model": { "type": "string", "description": "Model to use (optional)" }
            },
            "required": true
          }
        }
      }
    },
    {
      "name": "get_client_intelligence",
      "description": "Get comprehensive creator profile including niche, style, and performance data.",
      "method": "GET",
      "path": "/context/{clientId}",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true }
        }
      }
    },
    {
      "name": "get_platform_intelligence",
      "description": "Get latest algorithm insights for TikTok, Instagram, YouTube.",
      "method": "GET",
      "path": "/platform-intel",
      "parameters": {
        "type": "object",
        "properties": {
          "platforms": {
            "type": "array",
            "items": { "type": "string", "enum": ["TIKTOK", "INSTAGRAM", "YOUTUBE"] },
            "description": "Platforms to get intel for"
          }
        }
      }
    },
    {
      "name": "get_hook_recommendations",
      "description": "Get best performing hook archetypes for a creator.",
      "method": "GET",
      "path": "/tools",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "tool": { "type": "string", "const": "hooks" }
        }
      }
    },
    {
      "name": "get_optimal_timing",
      "description": "Get best days/times to post for maximum engagement.",
      "method": "GET",
      "path": "/tools",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "tool": { "type": "string", "const": "timing" }
        }
      }
    },
    {
      "name": "quick_post",
      "description": "All-in-one: upload video + create post + publish to platform.",
      "method": "POST",
      "path": "/posting/quick",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "platform": { "type": "string", "enum": ["TIKTOK", "INSTAGRAM", "YOUTUBE"], "required": true },
          "videoUrl": { "type": "string", "description": "URL to video file", "required": true },
          "caption": { "type": "string", "required": true },
          "hashtags": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    {
      "name": "ingest_data",
      "description": "Push platform data we can't access via API. This makes engagement_analysis 10x more accurate. Push retention curves, demographics, traffic sources, etc.",
      "method": "POST",
      "path": "/data/ingest",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "description": "Creator identifier", "required": true },
          "platform": { "type": "string", "enum": ["TIKTOK", "INSTAGRAM", "YOUTUBE"], "required": true },
          "dataType": { "type": "string", "description": "Type of data: retention, demographics, traffic_sources, watch_time, etc.", "required": true },
          "videoId": { "type": "string", "description": "Specific video ID (optional)" },
          "data": { "type": "object", "description": "The actual data as JSON", "required": true },
          "confidence": { "type": "number", "description": "Confidence in this data (0-1)", "default": 0.8 }
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "id": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    },
    {
      "name": "ingest_data_bulk",
      "description": "Push multiple data points at once (max 50 items).",
      "method": "POST",
      "path": "/data/ingest/bulk",
      "parameters": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "description": "Array of data items to ingest",
            "items": {
              "type": "object",
              "properties": {
                "clientId": { "type": "string", "required": true },
                "platform": { "type": "string", "enum": ["TIKTOK", "INSTAGRAM", "YOUTUBE"], "required": true },
                "dataType": { "type": "string", "required": true },
                "videoId": { "type": "string" },
                "data": { "type": "object", "required": true }
              }
            },
            "required": true
          }
        }
      }
    },
    {
      "name": "get_data_types",
      "description": "Get valid data types for each platform.",
      "method": "GET",
      "path": "/data/types",
      "parameters": { "type": "object", "properties": {} }
    },
    {
      "name": "get_ingested_data",
      "description": "Retrieve previously ingested data for a client.",
      "method": "GET",
      "path": "/data/{clientId}",
      "parameters": {
        "type": "object",
        "properties": {
          "clientId": { "type": "string", "required": true },
          "platform": { "type": "string", "enum": ["TIKTOK", "INSTAGRAM", "YOUTUBE"] },
          "dataType": { "type": "string" },
          "limit": { "type": "integer", "default": 20 }
        }
      }
    },
    {
      "name": "register_webhook",
      "description": "Register a webhook to receive async notifications.",
      "method": "POST",
      "path": "/webhooks",
      "parameters": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "HTTPS URL to receive webhooks", "required": true },
          "events": {
            "type": "array",
            "items": { "type": "string", "enum": ["skill.updated", "skill.version_created", "data.ingested", "validation.blocked", "posting.completed", "posting.failed"] },
            "description": "Events to subscribe to",
            "required": true
          },
          "secret": { "type": "string", "description": "Optional secret for signing (generated if not provided)" }
        }
      },
      "returns": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "secret": { "type": "string", "description": "Use to verify webhook signatures" }
        }
      }
    },
    {
      "name": "list_webhooks",
      "description": "List all registered webhooks for your agent.",
      "method": "GET",
      "path": "/webhooks",
      "parameters": { "type": "object", "properties": {} }
    },
    {
      "name": "delete_webhook",
      "description": "Unregister a webhook.",
      "method": "DELETE",
      "path": "/webhooks/{webhookId}",
      "parameters": {
        "type": "object",
        "properties": {
          "webhookId": { "type": "string", "required": true }
        }
      }
    },
    {
      "name": "get_status",
      "description": "Get service health status. No authentication required.",
      "method": "GET",
      "path": "/status",
      "parameters": { "type": "object", "properties": {} },
      "returns": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["operational", "degraded", "outage"] },
          "services": { "type": "object" },
          "metrics": { "type": "object" }
        }
      }
    }
  ],
  "use_cases": [
    {
      "title": "Long-term Memory",
      "description": "Store what works for each creator across sessions"
    },
    {
      "title": "Pattern Detection",
      "description": "See trends over months, not single data points"
    },
    {
      "title": "Data Ingestion",
      "description": "Push platform data we can't access for better recommendations"
    },
    {
      "title": "Content Generation",
      "description": "Get context before generating scripts/captions"
    },
    {
      "title": "Scheduling",
      "description": "Determine optimal posting times"
    },
    {
      "title": "Posting",
      "description": "Actually post to TikTok, Instagram, YouTube"
    },
    {
      "title": "Webhooks",
      "description": "Receive real-time notifications when events occur"
    },
    {
      "title": "Status Monitoring",
      "description": "Check service health before making requests"
    }
  ],
  "example": {
    "description": "Get memory for a creator",
    "request": {
      "method": "GET",
      "url": "https://api.crowterminal.com/api/agent/memory/client_123",
      "headers": {
        "Authorization": "Bearer mra_your_key"
      }
    },
    "response": {
      "success": true,
      "version": 47,
      "skill": {
        "primaryNiche": "fitness",
        "hookPatterns": ["confession", "transformation"],
        "avgEngagement": 4.2,
        "bestPostingTimes": [{"day": 2, "hour": 7, "score": 0.89}]
      }
    }
  }
}