Groovy Brain Spec v1 — Client Implementation Guide

1. Introduction

Brain Spec v1 is a standardized API specification that allows groovy.chat AI sales agents to understand, represent, and sell your product autonomously. By implementing a set of HTTP endpoints on your side, you give Groovy's agents deep knowledge of your capabilities, limitations, pricing rules, demo assets, and technical architecture.

What it powers:

• Autonomous lead qualification and outreach based on real product data
• Accurate, hallucination-free answers to prospect questions
• Intelligent demo selection tailored to each prospect's use case
• Confidence-scored capability assertions backed by technical evidence
• Plan-aware recommendations that respect your pricing tiers

Groovy syncs your Brain endpoints every 6 hours. Data is ingested into two internal knowledge stores — the Product Brain (sales-facing) and the Code Brain (technical assertions) — which agents query at runtime before every prospect interaction. If an agent cannot find an answer with sufficient confidence, it escalates to a human rather than guessing.

---

2. Quick Start

Implement these four required endpoints:

Steps:

1. Stand up the four endpoints on any HTTP server
2. Generate a Bearer token and share it with Groovy via the dashboard
3. Register your Brain URL in your workspace settings (e.g., https://api.yourproduct.com)
4. Groovy calls GET /brain/manifest to discover endpoints, then syncs all listed data

---

3. Authentication & Token Management

All endpoints require a Bearer token in the Authorization header.

copy

GET /brain/manifest HTTP/1.1
Host: api.yourproduct.com
Authorization: Bearer brn_live_a1b2c3d4e5f6...
Accept: application/json

• Tokens must be at least 32 characters
• Return 401 Unauthorized for invalid or missing tokens
• Return 403 Forbidden if the token is valid but lacks Brain Spec access

Token Lifecycle

Groovy generates and manages tokens from the dashboard:

1. Generate — A workspace admin generates a new token from Settings > Brain Source. The plaintext token is shown once — copy it immediately.
2. Configure — Paste the token into your Brain API as the expected Bearer value.
3. Revoke — If compromised, revoke the token from the dashboard. Sync stops immediately until a new token is generated.

Tokens are encrypted at rest (AES-256-GCM) and stored as SHA-256 hashes for revocation verification. Groovy never stores plaintext tokens after generation.

---

3.1 Security

Groovy enforces multiple layers of security on the sync flow:

Content Sanitization Details

Every field of every brain data type is sanitized between fetch and RAG ingestion:

• XSS: Strips <script>, <iframe>, <object>, <embed>, <form>, <input>, <link>, <meta>, event handler attributes (onload, onerror, etc.), and javascript: URIs
• Prompt injection: Detects common injection patterns (system prompt overrides, role impersonation, instruction injection) and logs warnings without blocking
• URL validation: Rejects URLs with javascript:, data:, or vbscript: schemes, credentials in the URL, and private/reserved IP addresses
• Size limits: Text fields truncated to 10,000 characters, short fields to 500 characters, arrays capped at 1,000 items

---

4. Envelope Format

All endpoints except /brain/manifest wrap their response in a standard envelope:

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:a3f2b8c1d4e5...",
  "data": [ ... ]
}

Layer	Protection
Auth	Session-based auth (dashboard) or Bearer token (API). Only workspace owner or admin roles can modify Brain config.
Encryption at rest	API tokens are encrypted with AES-256-GCM before storage. Decrypted only at sync time in-memory.
Token revocation	Instant revocation via dashboard. Hash-based verification — no plaintext comparison needed.
SSRF protection	Brain source URLs are validated against private IP ranges, localhost, link-local, and cloud metadata endpoints (169.254.169.254).
Rate limiting	Per-workspace limits: 5 syncs/hour, 10 connection tests/minute, 20 config operations/minute.
Payload size limit	Maximum 5 MB per endpoint response. Responses exceeding this are rejected before parsing.
Content sanitization	All synced data passes through a sanitization chain before ingestion: XSS tag stripping, prompt injection detection, URL validation, and field-level size limits (10,000 chars per text field, 1,000 items per array).
UUID validation	All workspace IDs are validated as strict UUID v4 format before any database query.
Error sanitization	Error messages returned to clients are stripped of database details, stack traces, and internal paths.

Field	Type	Description
version	string	Your data version (semver recommended)
lastUpdated	string	ISO 8601 timestamp of the last data change
checksum	string	SHA-256 hex digest of JSON.stringify(data), prefixed with sha256:
data	T	The payload array or object for the endpoint

Groovy uses checksum to detect changes and skip re-ingestion when data hasn't changed.

---

5. Manifest Endpoint

copy

GET /brain/manifest

The entry point. Groovy calls it first to discover which endpoints you support. Not wrapped in an envelope.

copy

{
  "specVersion": "1.0",
  "productName": "Taskflow",
  "productSlug": "taskflow",
  "availableEndpoints": [
    "product/capabilities",
    "product/limitations",
    "product/faq",
    "product/use-case-mappings",
    "product/demo-catalog",
    "code/capability-assertions"
  ]
}

Field	Type	Description
specVersion	string	Always "1.0" for this spec version
productName	string	Human-readable product name
productSlug	string	URL-safe identifier (lowercase, hyphens only)
availableEndpoints	string[]	Implemented endpoints (without /brain/ prefix)

Groovy only calls endpoints listed in availableEndpoints.

---

6. Product Brain Endpoints

6.1 Capabilities — GET /brain/product/capabilities

Returns ProductCapability[]. Core product knowledge with availability, plan restrictions, and cross-references.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:e4a1c3f9b2d7...",
  "data": [
    {
      "id": "cap-001",
      "slug": "kanban-boards",
      "name": "Kanban Boards",
      "category": "Task Management",
      "summary": "Drag-and-drop Kanban boards with customizable columns.",
      "description": "Create unlimited Kanban boards with custom columns, WIP limits, swimlanes, and card templates. Supports drag-and-drop reordering and real-time collaboration.",
      "status": "available",
      "available": true,
      "supportedPlans": ["starter", "pro", "enterprise"],
      "supportedPersonas": ["project-manager", "team-lead", "developer"],
      "relatedUseCaseIds": ["uc-agile-workflow"],
      "relatedDemoIds": ["demo-kanban-overview"],
      "limitations": ["WIP limits only on Pro and above"],
      "caveats": ["Column limit of 20 per board on Starter plan"],
      "proofRefs": ["https://docs.taskflow.io/kanban"],
      "faqAnswerIds": ["faq-003"],
      "tags": ["core", "collaboration", "agile"],
      "lastVerifiedAt": "2025-11-10T14: 00: 00Z",
      "version": "1.0.0"
    }
  ]
}

Field reference:

6.2 Limitations — GET /brain/product/limitations

Returns ProductLimitation[]. Agents use these to set accurate expectations and avoid overpromising.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:b7d2e5f8a1c3...",
  "data": [
    {
      "id": "lim-001",
      "capabilityId": "cap-002",
      "title": "No Android timer",
      "description": "The time tracking timer is not yet available on Android. Users must use the web app or iOS. Android support is on the roadmap for Q1 2026.",
      "limitationType": "platform",
      "severity": "important",
      "escalationRequired": false,
      "lastVerifiedAt": "2025-11-10T14: 00: 00Z",
      "version": "1.0.0"
    },
    { "id": "lim-002", "capabilityId": null, "title": "File storage cap of 5GB on Starter", "severity": "critical", "escalationRequired": true, "..." : "..." }
  ]
}

Field	Type	Description
id, slug, name	string	Identifiers
category	string	Grouping category
summary	string	One-line summary (used in emails)
description	string	Full description (used in detailed answers)
status	enum	"available", "partial", "not_available", "deprecated"
available	boolean	Quick boolean for filtering
supportedPlans	string[]	Plan slugs where this is available
supportedPersonas	string[]	Persona slugs this is relevant to
relatedUseCaseIds	string[]	Cross-ref to use case mappings
relatedDemoIds	string[]	Cross-ref to demo assets
limitations	string[]	Known limitations (shown to prospects)
caveats	string[]	Internal caveats for agent context
proofRefs	string[]	URLs to docs/screenshots as evidence
faqAnswerIds	string[]	Cross-ref to FAQ answers
tags	string[]	Freeform tags for search

6.3 FAQ — GET /brain/product/faq

Returns SalesFaqAnswer[]. Pre-approved answers that agents use verbatim (strict) or as context (contextual).

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:c8e3f6a9d1b4...",
  "data": [
    {
      "id": "faq-003",
      "canonicalQuestion": "How many users can I have on a board?",
      "questionType": "pricing",
      "approvedAnswer": "All plans support unlimited board members. Starter allows up to 10 workspace members, while Pro and Enterprise have no limits.",
      "answerMode": "strict",
      "escalationRequired": false,
      "relatedCapabilityIds": ["cap-001"],
      "relatedLimitationIds": [],
      "relatedDemoIds": [],
      "tags": ["pricing", "limits"],
      "owner": "sales-ops",
      "lastReviewedAt": "2025-11-01T10: 00: 00Z",
      "version": "1.0.0"
    }
  ]
}

| Field | Type | Description |

|-------|------|-------------|

| answerMode | enum | "strict" (use verbatim) or "contextual" (agent may adapt) |

| escalationRequired | boolean | If true, agents escalate instead of answering |

| owner | string | Team or person responsible for this answer |

6.4 Use Case Mappings — GET /brain/product/use-case-mappings

Returns UseCaseMapping[]. Maps persona + use case to recommended capabilities and demos.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:d9f4a7b2c5e8...",
  "data": [
    {
      "id": "uc-agile-workflow",
      "personaSlug": "project-manager",
      "useCaseSlug": "agile-workflow",
      "useCaseTitle": "Agile Sprint Management",
      "useCaseDescription": "Manage agile sprints with Kanban boards, backlog grooming, and velocity tracking.",
      "painPoints": [
        "Scattered tasks across Slack, email, and spreadsheets",
        "No visibility into sprint progress for stakeholders"
      ],
      "recommendedCapabilityIds": ["cap-001", "cap-005"],
      "recommendedDemoIds": ["demo-kanban-overview"],
      "recommendedCTA": "See how Taskflow replaces your spreadsheet sprint board in 2 minutes",
      "version": "1.0.0"
    }
  ]
}

6.5 Demo Catalog — GET /brain/product/demo-catalog

Returns DemoAsset[]. Interactive demos that agents send to prospects at the right moment.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:e1a5b8c2d6f9...",
  "data": [
    {
      "id": "demo-kanban-overview",
      "slug": "kanban-overview",
      "title": "Kanban Boards — Full Walkthrough",
      "description": "Interactive walkthrough of creating a board, adding tasks, and setting WIP limits.",
      "supademoUrl": "https://app.supademo.com/demo/abc123",
      "language": "en",
      "personaTargets": ["project-manager", "team-lead"],
      "useCaseSlugs": ["agile-workflow"],
      "relatedCapabilityIds": ["cap-001"],
      "estimatedDurationSeconds": 180,
      "priority": 1,
      "isActive": true,
      "version": "1.0.0"
    }
  ]
}

6.6 Plan Rules — GET /brain/product/plan-rules

Returns PlanRule[]. Defines capability inclusion/exclusion per pricing plan.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:f2b6c9d3e7a1...",
  "data": [
    {
      "id": "plan-starter",
      "planSlug": "starter",
      "planName": "Starter",
      "includedCapabilityIds": ["cap-001", "cap-003", "cap-004"],
      "excludedCapabilityIds": ["cap-002", "cap-006"],
      "limitations": ["10 workspace members max", "5GB file storage", "Community support only"],
      "version": "1.0.0"
    },
    { "id": "plan-pro", "planSlug": "pro", "planName": "Pro", "..." : "..." }
  ]
}

6.7 Narratives — GET /brain/product/narratives

Returns ApprovedNarrative[]. Pre-approved sales narratives (elevator pitches, objection handlers, ROI stories).

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:a3c7d1e5f9b2...",
  "data": [
    {
      "id": "narr-001",
      "narrativeType": "elevator_pitch",
      "title": "30-Second Pitch for Engineering Leads",
      "audience": ["team-lead", "developer"],
      "body": "Taskflow is the project management tool built for engineering teams. Replace your Jira + Notion + spreadsheet stack with one tool that handles sprint planning, time tracking, and release management.",
      "relatedCapabilityIds": ["cap-001", "cap-002", "cap-005"],
      "version": "1.0.0",
      "lastReviewedAt": "2025-11-01T10: 00: 00Z"
    }
  ]
}

---

7. Code Brain Endpoints

Technical evidence that backs up product capability claims. Provides confidence scores and answers to architecture questions.

7.1 Capability Assertions — GET /brain/code/capability-assertions

Returns CapabilityAssertionSpec[]. Links product capabilities to specific modules, API routes, and data models as proof.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:b4d8e2f6a0c3...",
  "data": [
    {
      "id": "assert-001",
      "capabilityId": "cap-001",
      "capabilitySlug": "kanban-boards",
      "status": "available",
      "confidence": "high",
      "technicalEvidence": {
        "modules": ["src/modules/boards/kanban.ts", "src/modules/boards/columns.ts"],
        "apiRoutes": ["/api/v1/boards", "/api/v1/boards/:id/columns"],
        "dataModels": ["Board", "Column", "Card"],
        "featureFlags": [],
        "adminScreens": ["/admin/boards"]
      },
      "limitations": [],
      "notes": "Full Kanban implementation with real-time sync via WebSockets.",
      "verifiedBy": "engineering",
      "lastVerifiedAt": "2025-11-10T14: 00: 00Z",
      "version": "1.0.0"
    }
  ]
}

Field	Type	Description
capabilityId	string?	Linked capability (null if global limitation)
limitationType	string	Category: "platform", "plan_restriction", "quota", "integration"
severity	enum	"info", "important", "critical"
escalationRequired	boolean	If true, agents escalate to a human instead of answering

7.2 API Surface — GET /brain/code/api-surface

Returns ApiSurfaceItemSpec[]. Public API endpoints for technical integration questions.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:c5e9f3a7b1d4...",
  "data": [
    {
      "id": "api-001",
      "route": "/api/v1/boards",
      "method": "GET",
      "description": "List all boards in the workspace. Supports pagination and filtering by status.",
      "auth": "Bearer token (API key)",
      "relatedCapabilityIds": ["cap-001"],
      "tags": ["boards", "read"],
      "version": "1.0.0"
    },
    { "id": "api-002", "route": "/api/v1/webhooks", "method": "POST", "description": "Register a webhook for real-time event notifications.", "..." : "..." }
  ]
}

7.3 Data Model Map — GET /brain/code/data-model-map

Returns DataModelItem[]. Core data models with fields and relationships.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:d6f0a4b8c2e5...",
  "data": [
    {
      "id": "dm-001",
      "name": "Board",
      "description": "A Kanban or list-view board belonging to a workspace.",
      "fields": ["id", "name", "description", "workspace_id", "board_type", "created_at", "archived_at"],
      "relations": ["Workspace (belongs_to)", "Column (has_many)", "Card (has_many through Column)"],
      "relatedCapabilityIds": ["cap-001"],
      "tags": ["core", "boards"],
      "version": "1.0.0"
    }
  ]
}

7.4 Module Map — GET /brain/code/module-map

Returns ModuleMapItem[]. Codebase module structure for architectural context.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:e7a1b5c9d3f6...",
  "data": [
    {
      "id": "mod-001",
      "modulePath": "src/modules/boards",
      "moduleName": "Boards Module",
      "purpose": "Core board management: CRUD for boards, columns, and cards. Includes Kanban logic and real-time sync.",
      "relatedCapabilityIds": ["cap-001"],
      "tags": ["core", "boards"],
      "version": "1.0.0"
    }
  ]
}

7.5 Release Notes — GET /brain/code/release-notes

Returns ReleaseNote[]. Recent changes so agents can reference new features in conversations.

copy

{
  "version": "1.0.0",
  "lastUpdated": "2025-11-15T09: 30: 00Z",
  "checksum": "sha256:f8b2c6d0e4a7...",
  "data": [
    {
      "id": "rel-2.4.0",
      "version": "2.4.0",
      "releaseDate": "2025-11-12",
      "changes": [
        "Added swimlanes to Kanban boards",
        "Improved time tracking report export with custom date ranges",
        "Fixed column reordering bug on Safari"
      ],
      "affectedCapabilityIds": ["cap-001", "cap-002"],
      "notes": "Swimlanes available on all plans. Custom date range export requires Pro."
    }
  ]
}

---

8. Required vs Optional Endpoints

Field	Type	Description
status	enum	"available", "partial", "unsupported", "deprecated"
confidence	enum	"high", "medium", "low"
technicalEvidence.modules	string[]	Source code file paths
technicalEvidence.apiRoutes	string[]	API endpoint routes
technicalEvidence.dataModels	string[]	Database model names
technicalEvidence.featureFlags	string[]	Feature flags (optional)
technicalEvidence.adminScreens	string[]	Admin UI paths (optional)
verifiedBy	string	Who verified this assertion

Endpoint	Status	Impact
GET /brain/manifest	Required	Discovery entry point
GET /brain/product/capabilities	Required	Core product knowledge
GET /brain/product/limitations	Required	Prevents overpromising
GET /brain/product/faq	Required	Pre-approved answers
GET /brain/product/use-case-mappings	Optional	Improves persona targeting
GET /brain/product/demo-catalog	Optional	Enables automated demo delivery
GET /brain/product/plan-rules	Optional	Plan-aware recommendations
GET /brain/product/narratives	Optional	Improves outreach messaging
GET /brain/code/capability-assertions	Optional	Adds confidence scoring
GET /brain/code/api-surface	Optional	Enables technical Q&A
GET /brain/code/data-model-map	Optional	Data architecture Q&A
GET /brain/code/module-map	Optional	Codebase context
GET /brain/code/release-notes	Optional	"What's new" conversations

Recommended rollout order: Start with the 4 required endpoints, then add use-case-mappings, demo-catalog, and capability-assertions for the highest incremental impact.

---

9. Validation Checklist

Authentication

• All endpoints return 401 for missing or invalid Bearer tokens
• Tokens are at least 32 characters

Manifest

• GET /brain/manifest returns valid JSON (no envelope)
• specVersion is "1.0"
• availableEndpoints lists only endpoints you actually implemented
• productSlug is lowercase with hyphens only

Envelope

• All endpoints (except manifest) return version, lastUpdated, checksum, data
• lastUpdated is a valid ISO 8601 timestamp
• checksum matches sha256: + hex of SHA-256(JSON.stringify(data))

Data Integrity

• All id fields are unique within their endpoint
• Cross-references point to valid IDs
• status fields use only allowed enum values
• Timestamps are valid ISO 8601

Performance

• Endpoints respond within 10 seconds
• Payload size is under 5 MB per endpoint

Security

• No <script>, <iframe>, or event handler attributes in text fields
• No javascript: or data: URLs in proof/link fields
• No credentials or tokens embedded in URLs
• Text fields stay under 10,000 characters
• Arrays have fewer than 1,000 items per endpoint

Quick Smoke Test

copy

# 1. Check manifest
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.yourproduct.com/brain/manifest | jq .

# 2. Verify capabilities returns an envelope
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.yourproduct.com/brain/product/capabilities | jq '{version, checksum, count: (.data | length)}'

# 3. Validate checksum
RESPONSE=$(curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.yourproduct.com/brain/product/capabilities)
EXPECTED=$(echo "$RESPONSE" | jq -r '.data' | shasum -a 256 | cut -d' ' -f1)
ACTUAL=$(echo "$RESPONSE" | jq -r '.checksum' | sed 's/sha256://')
[ "$EXPECTED" = "$ACTUAL" ] && echo "Checksum valid" || echo "Checksum mismatch"

# 4. Auth rejection (should return 401)
curl -s -o /dev/null -w "%{http_code}" https://api.yourproduct.com/brain/manifest

---

10. FAQ for Developers

How often does Groovy sync my Brain data?

Every 6 hours by default. Groovy checks the checksum first and skips re-ingestion if data hasn't changed. You can trigger an immediate sync from the dashboard.

Can I host the Brain endpoints on a different domain?

Yes. Configure the Brain URL in your Groovy workspace settings. Any publicly accessible HTTPS endpoint works.

What happens if an endpoint goes down?

Groovy retries 3 times with exponential backoff. On failure, agents use the last successfully synced data. A warning appears in the dashboard.

Do I need all 13 endpoints?

No. Only 4 are required (manifest, capabilities, limitations, faq). Only list implemented endpoints in your manifest.

How should I generate IDs?

Use any stable, unique string. UUIDs, slugs (cap-kanban-boards), or sequential IDs all work. IDs must be stable across syncs -- changing an ID is treated as a deletion + creation.

How is the checksum computed?

copy

const crypto = require("crypto");
function computeChecksum(data) {
  const raw = JSON.stringify(data);
  const hash = crypto.createHash("sha256").update(raw).digest("hex");
  return `sha256:${hash}`;
}

What if a capability is behind a feature flag?

Set status to "partial" and list the flag in the corresponding CapabilityAssertion.technicalEvidence.featureFlags. Add a note in caveats.

How do I handle deprecated features?

Set status to "deprecated" and available to false. Keep it in the response so agents can explain the deprecation. Add a limitation entry with context about the replacement.

Can I add custom fields?

Groovy ignores unknown fields, so custom fields won't break anything. However, agents will not use them. Contact us to discuss spec extensions.

What happens if my token is compromised?

Revoke it immediately from Settings > Brain Source in the dashboard. Sync stops until you generate a new token. Revocation is instant — the old token cannot be used again.

Are there payload size limits?

Yes. Each endpoint response must be under 5 MB. Groovy rejects larger payloads before parsing. Keep text fields under 10,000 characters and arrays under 1,000 items.

Does Groovy sanitize my data?

Yes. All synced data passes through XSS stripping, prompt injection detection, URL validation, and size enforcement before ingestion. Malformed content is cleaned or truncated, never silently accepted into the knowledge base.

Is there a sandbox?

Yes. Use staging.groovy.chat with a test workspace. Brain endpoints sync normally, but no real outreach is sent.

Where can I find a reference implementation?

Complete working examples in Node.js, Python, and Go are available at Quick Start Examples.