Technical Documentation

Every signal contains these core fields:

Your CSV should have a header row. Clarion recognizes these column names (case-insensitive):

title,rawContent,customerName,customerEmail,customerCompany,customerArr
"Need dark mode","Our entire team works late and the bright UI is painful","Jane Smith","jane@acme.com","Acme Corp",120000
"API rate limiting","Getting 429s when syncing more than 100 records","Bob Lee","bob@widgets.io","Widgets Inc",45000

• Maximum file size: 5 MB
• Maximum rows per upload: 1,000
• Duplicate detection: signals with identical rawContent within 24 hours are automatically skipped.

1. 1

   Create a webhook

   Give it a name (e.g., “Typeform Feedback”) and optionally restrict accepted source types. Clarion generates a unique URL and a signing secret.
2. 2

   Configure your source

   Point your external system to the generated URL. Include the signing secret as an X-Webhook-Secret header for HMAC verification.
3. 3

   Send signals

   POST a JSON payload matching the signal schema. Clarion validates, enqueues, and processes each signal automatically.

For security, Clarion signs every expected payload with your webhook secret using HMAC-SHA256. Include the secret in the X-Webhook-Secret header. Requests with missing or invalid signatures are rejected with a 401 status.

• What syncs: Support tickets (subject, description, priority, status, tags, assignee, channel, via, timestamps).
• Auth: Secure OAuth. Clarion requests read-only access to tickets.
• Sync frequency: On-demand or scheduled. Default lookback window is 24 hours.
• Field mapping: Zendesk subject → signal title, description → rawContent. Priority, status, tags, and timestamps are stored in sourceMetadata.

• What syncs: Conversations (messages, user info, tags, conversation state).
• Auth: OAuth 2.0. Read-only access to conversations and users.
• Field mapping: Conversation body → rawContent. User name, email, and company are mapped to customer fields.

• What syncs: Call recordings and transcripts. Speaker segments, topics, and action items.
• Auth: OAuth 2.0. Read-only access to calls and transcripts.
• Processing: Transcripts are chunked into individual feedback signals based on speaker turns and topic shifts.

• What syncs: Analytics events, user properties, and cohort data.
• Auth: API key + secret. Read-only access to event data.
• Use case: Quantitative signals — feature usage patterns, drop-off points, engagement metrics — complement qualitative feedback from other sources.

• Purpose: Push generated agent artifacts (.cursorrules, tasks.json, test scenarios) directly to a GitHub repository as a new branch and pull request.
• Auth: GitHub OAuth App. Requires write access to selected repositories.
• PR webhooks: Clarion listens for PR merge events to automatically detect shipped features and update opportunity status.

• Purpose: Receive anomaly alerts, digest reports, and notification summaries directly in Slack channels.
• Setup: Configure a Slack webhook URL in Settings → Notifications.

Each processed signal produces these fields on its linked insight record:

Signals with classification confidence below 70% are flagged in a review queue for manual verification.

After generating a machine spec, generate five agent artifacts optimized for AI coding assistants:

Export specs formatted for specific AI coding tools:

Push generated artifacts directly to a GitHub repository. Clarion creates a new branch, commits all artifact files, and opens a pull request. When the PR is merged, Clarion automatically detects the shipped feature and updates the linked opportunity status.

Specs are validated for completeness and consistency. The validator checks for missing acceptance criteria, undefined API contracts, inconsistent data models, and untested edge cases. Validation results are shown inline as gap indicators before artifact generation.

The @clarion/cli package auto-detects your agent and writes the right skill files, rules-file snippets, and MCP config for you. All writes are idempotent — safe to re-run.

npx @clarion/cli@latest init
npx @clarion/cli@latest login

Restart your agent. For the full per-agent reference (file paths, manual setup, troubleshooting), see agent-setup.md.

Clarion's MCP server exposes nine tools today. Decision logging, document browsing, and full drift validation are coming in upcoming releases — tools that depend on them fall back gracefully until then.

MCP connections use OAuth 2.0 with PKCE — no API key copy-paste. The CLI handles the loopback flow for you. Tokens are scoped per workspace and refresh automatically (1-hour access tokens, 30-day refresh tokens).

Project-level .mcp.json (Cursor, Claude Code, Copilot, Windsurf, Cline, Junie):

{
  "mcpServers": {
    "clarion": {
      "url": "https://app.getclarion.in/api/mcp"
    }
  }
}

Codex uses a user-global TOML config:

[mcp_servers.clarion]
url = "https://app.getclarion.in/api/mcp"

For headless CI/scripts where OAuth isn't practical, fall back to an API key — set CLARION_API_KEY=<key> as an env var. Generate one in Settings → API Keys.

MCP clients discover Clarion's OAuth endpoints from /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728). Dynamic Client Registration (RFC 7591) at /api/mcp/oauth/register means clients get a stable client_id without you registering anything by hand.

Connecting MCP isn't enough — your agent needs to know when to call Clarion. The CLI writes a SKILL.mdwith explicit trigger rules (e.g. “Call clarion_get_onboarding_context once per session; call clarion_ask mode=check before strategic implementation choices”) plus anti-patterns and output norms (cite by entity id, attribute by company, never fabricate ARR numbers).

For Claude Code, the CLI also writes /clarion-setup, /clarion-welcome-back, /clarion-check <approach>, and /clarion-decide <decision> slash commands. Other agents recognize the same phrases as plain messages.

npx @clarion/cli@latest whoami      # confirms CLI authentication
npx @clarion/cli@latest context     # workspace snapshot
# Then in your agent:
> Call clarion_get_onboarding_context and tell me what you see.

The Agent Bridge page (/agents) lists every host that's currently connected via OAuth or API key, with last-used timestamps and a revoke button per token.

Generate API keys in Settings → API Keys. Include the key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer cl_your_api_key" \
  https://getclarion.in/api/v1/signals

Signals

Insights & Opportunities

Specifications

Webhooks

Search & Knowledge

All successful responses return a JSON object with a data key. List endpoints include pagination metadata:

{
  "data": [
    {
      "id": "01960a3b-...",
      "title": "Need bulk export option",
      "rawContent": "Our team needs to export reports as PDF...",
      "sourceType": "zendesk",
      "status": "PROCESSED",
      "category": "feature_request",
      "customer": {
        "id": "01960a3a-...",
        "name": "Jane Smith",
        "company": "Acme Corp"
      },
      "createdAt": "2026-02-15T10:30:00Z"
    }
  ],
  "nextCursor": "01960a3b-...",
  "total": 142
}

List endpoints use cursor-based pagination. Pass cursor (the ID of the last item) and limit (default 20, max 100) as query parameters. The response includes a nextCursor field for the next page.

API requests are rate-limited per API key. Limits depend on your plan (see User Guide for full plan details):

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.

All errors follow a consistent JSON format:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE"
}

• In transit: TLS 1.2+ for all connections. Automatic HTTPS with managed SSL certificates.
• At rest: Sensitive fields (API keys, integration tokens, webhook secrets) encrypted with AES-256-GCM using unique initialization vectors per field.
• Passwords: Securely hashed using industry-standard algorithms. Never stored in plain text.

All data is strictly isolated by organization. Every request is scoped to your organization. There is no way to access another organization’s data through any API endpoint or UI interaction.

• Sessions: JWT-based with secure, HTTP-only tokens. 30-day expiry.
• OAuth: Google OAuth 2.0 for social login.
• API keys: SHA-256 hashed, displayed once at creation, revocable instantly.
• RBAC: Four permission levels — Owner, Admin, Member, Viewer — with granular access control per feature.
• Login activity: IP address, browser, timestamp, and geolocation logged for all authentication events. Retained for 90 days.

• Your data is processed by Clarion AI in real-time and is never stored beyond the immediate request.
• Your data is never used to train, fine-tune, or improve any AI model.
• AI processing is per-organization — your data is never mixed with another organization’s data.
• Only the minimum data needed for each AI task is sent — not your entire database.

• Hosted on Google Cloud Platform.
• Network firewalls restrict access to required ports only.
• Database backups retained for 7 days.
• Regular dependency updates and security patches.

Invite team members from Settings → Team. Each invitation specifies a role. For Pro plans, you can optionally assign a Pro seat to the invited member (giving them access to Pro features). Invitations are delivered via email and expire after 7 days.

You can also create shareable invite links for bulk onboarding. Invite links can be configured with a maximum number of uses and an expiration date.

Users can belong to multiple organizations. Switch between orgs from the sidebar dropdown menu. Each org has its own data, settings, and billing — completely isolated.