ReferenceJSON Schema

The Manifest

Every plugin starts with a manifest.json. This file tells Cortex who you are, how to talk to you, and what tools you provide.

1Anatomy of a Manifest

The manifest is a strict JSON document. It must be hosted on a public URL (e.g., GitHub Gist or your own server) during installation.

json

{
  "slug": "ACME_CRM",
  "version": "1.0.0",
  "name": "Acme CRM Integration",
  "description": "Connects your bot to Acme CRM to manage contacts.",
  "author": {
    "name": "Acme Corp",
    "email": "dev@acme.com",
    "url": "https://acme.com"
  },
  "baseUrl": "https://api.acme.com/cortex-webhook",
  
  // AUTH: Shared Secret (Default)
  "auth": {
    "type": "platform_token"
  },
  
  "tools": [
    {
       "name": "get_contact",
       "description": "Look up a contact by email",
       "inputSchema": {
         "type": "object",
         "properties": {
           "email": { "type": "string" }
         },
         "required": ["email"]
       }
    }
  ]
}

2Field Reference

slug

REQUIRED

string

Unique identifier for your plugin using UPPER_SNAKE_CASE. Must match your API service name.

version

REQUIRED

string

Semantic version (e.g. 1.0.0). Cortex uses this to track updates.

baseUrl

REQUIRED

url

The public HTTPS endpoint where Cortex will send requests. Must happen over SSL.

auth

object

Authentication configuration. Defaults to `type: 'platform_token'` if omitted.

tools

REQUIRED

array

List of functions your plugin exposes to the AI Agent.

3Defining Tools & Execution Patterns

Tools are the specific capabilities your plugin grants to the AI. While the platform offers a "convention-over-configuration" default, you have full control over the HTTP interface to match your existing infrastructure.

Pattern A: The Global Webhook

By omitting the endpoint configuration, you adopt the **Standard Dispatch** pattern. This is the recommended approach for new projects.

How it behaves:

Cortex sends a POST request to your baseUrl + /execute.
The AI switches between tools internally by checking the "tool" field in the request body.
Perfect for Serverless functions (AWS Lambda, Vercel) where you want a single entry point.

Example Mapping

json

{
  "name": "calculate_tax",
  "description": "Calculates sales tax for a dollar amount",
  "inputSchema": {
    "type": "object",
    "properties": {
      "amount": { "type": "number" }
    }
  }
  // Result: POST {baseUrl}/execute
}

Pattern B: Explicit Routing

If you are connecting Cortex to an existing REST API or a monolithic service, you can map individual tools to specific URL paths.

Why use this?

**Cleaner Logs**: Each tool shows up as a distinct URL in your server logs.
**Middleware Control**: Apply specific rate-limiting or validation logic to individual routes.
**Microservices**: Map different tools in the same manifest to different microservices sitting behind a gateway.

Custom Endpoint

json

{
  "name": "create_user",
  "description": "Registers a new user in the system",
  "inputSchema": { ... },
  "endpoint": {
    "path": "/api/v2/onboarding/register"
  }
  // Result: POST {baseUrl}/api/v2/onboarding/register
}

Pattern C: Semantic Methods

Some tools are purely informational and don't modify data. For these, use GET or PUT as appropriate.

Important Implementation Detail

When using GET, Cortex converts the tool execution into a header-only request. No JSON body is sent. Your server must rely on the X-User-ID and Authorization headers to identify the user and context.

Status Query

json

{
  "name": "check_inventory",
  "description": "Queries stock levels for a product",
  "inputSchema": { ... },
  "endpoint": {
    "method": "GET",
    "path": "/inventory/status"
  }
  // Result: GET {baseUrl}/inventory/status
}

Naming Convention

Always name tools as **Active Verbs** using snake_case (e.g., generate_report). The AI uses the name as a strong semantic hint; names like tool1 or action will confuse the routing engine.

HTTPS & Security

Cortex strictly enforces **SSL/TLS**. All baseUrl and tool path values must be served over HTTPS. Requests to non-secure endpoints will be blocked at the gateway level.