# live-neon

> AI agent identity platform. Define, observe, and evolve structured identities for AI agents — beliefs, responsibilities, and system prompts that stay consistent across any LLM or framework.

Base URL: https://agentpersona.live/api/v1 (also works without /v1 — both /api/v1/ and /api/ are identical)
Docs: https://agentpersona.live/docs/api
OpenAPI: https://agentpersona.live/openapi.json
Agent Card: https://agentpersona.live/.well-known/agent-card.json
Comparisons: https://agentpersona.live/compare — side-by-side comparisons with 20+ alternatives including GitAgent, CrewAI, OpenAI Frontier, LangSmith, Karpathy CLAUDE.md, and more

## MCP Server (Preferred for AI Agents)

Install: npx -y mcp-persona
npm: https://www.npmjs.com/package/mcp-persona

Prefer MCP over REST if your client supports it (Claude Desktop, Claude Code, Cursor, Windsurf). The MCP server wraps the full REST API as 44 tools, 5 resources, and 3 prompts. Zero-config: use the register tool to get an API key automatically.

Claude Code: claude mcp add persona -- npx -y mcp-persona
Config: { "mcpServers": { "persona": { "command": "npx", "args": ["-y", "mcp-persona"], "env": { "PERSONA_API_KEY": "ln_your_key" } } } }

## Authentication

Programmatic Registration: POST /api/v1/register — zero fields required, no auth needed. Creates account + org + API key in one call. Email optional (for account recovery). Returns `your_token` immediately. This is the recommended path for AI agents. Rate limited: 5 req/min per IP.

Account Management: GET /api/v1/account (view), PATCH /api/v1/account (update email/password/display_name). Auth: Bearer token or session.

API Keys: Create an org-scoped key in your organization's settings page, or get one automatically via POST /api/v1/register. Header: Authorization: Bearer ln_<key>. Keys are prefixed with `ln_` and scoped to a single org. The org is auto-inferred from the key.

Organization Resolution: All endpoints accept orgId (UUID) or orgSlug (e.g., "my-org") interchangeably. Path segments like /api/v1/organizations/{orgId}/ also accept slugs. When using API key auth, the org is auto-inferred if neither is provided.

## Free Tools (No Auth Required)

Public Identity Analyzer: POST /api/public/analyze — paste any agent identity file (CLAUDE.md, SOUL.md, .cursorrules, agents.yaml, system prompts) and get structured analysis with beliefs, responsibilities, gaps, and token efficiency. No auth, no signup. Rate limited: 10 req/min per IP.

Framework-specific pages:
- https://agentpersona.live/analyze/claude-md — Claude Code
- https://agentpersona.live/analyze/cursor-rules — Cursor
- https://agentpersona.live/analyze/agents-md — AGENTS.md (cross-platform)
- https://agentpersona.live/analyze/copilot-instructions — GitHub Copilot
- https://agentpersona.live/analyze/crewai — CrewAI
- https://agentpersona.live/analyze/windsurf-rules — Windsurf
- https://agentpersona.live/analyze/system-prompt — Any system prompt

CLAUDE.md Generation: POST /api/v1/agents/{id}/dynamic-prompt with format=claude_md — generates a natural CLAUDE.md from agent identity. Supports template enhancement (pass existing file), context-aware selection, and feedback integration.

Comparison Pages: https://agentpersona.live/compare — 23 side-by-side comparison pages covering direct competitors (GitAgent, PersonaNexus, SoulClaw, Solitaire), enterprise platforms (OpenAI Frontier, LangSmith Fleet), agent frameworks (CrewAI, AutoGen), prompt management (Humanloop, Langfuse, Vellum), observability (Arize, Braintrust), governance (Openlayer), standards (Oracle Agent Spec, Soul Spec), CLAUDE.md ecosystem (Karpathy, Anthropic plugin, cursorrules.org), and category justification (vs static CLAUDE.md, vs DIY, vs no platform). Each page includes feature comparison tables, migration guides, and FAQs with structured data markup.

## Important Notes

- API version: v1 (breaking changes avoided within v1)
- Rate limits enforced per API key/IP: general 200 req/min, heavy ops (sync/PBD) 30 req/min, bulk 10 req/min, auth 20 req/min. Returns 429 with Retry-After header
- No webhooks or callbacks for async operations — poll for results
- Observations and signals are read-only (generated by PBD pipeline)
- All list endpoints support limit/offset pagination and return { data, count }
- All endpoints accept both camelCase and snake_case input via normalizeRequestKeys()
- OpenAPI spec available at /openapi.json

## Core Concepts

- Organizations: multi-tenant isolation, all resources scoped by org_id
- Agents: AI agents with structured identity (beliefs + responsibilities), optional github_username for commit attribution, and generated system prompts
- Soul (Beliefs): agent identity across 5 categories (axiom, principle, voice, preference, boundary)
- Responsibilities: agent accountabilities across 5 categories (ownership, execution, collaboration, deliverables, monitoring)
- System Prompt: auto-generated by merging org + group + agent beliefs/responsibilities + location/timezone, cached on agent
- Hierarchical Personas: three-layer identity (org → group → agent). Org beliefs cascade to all agents, group beliefs cascade to group members. Agent overrides let individual agents hide inherited items.
- Dynamic Prompt: per-invocation randomized prompt variant that combats persona numbing (opt-in, configurable sampling per category)
- Groups: organizational groupings with optional cross-group manager
- Environments: deployment contexts (production, staging)
- Models: LLM configurations (provider + model ID), assigned to agents per environment
- PBD (Pattern-Based Discovery): 3-stage pipeline — extract observations → cluster into signals → promote to beliefs AND responsibilities
- Consensus Promotion: when agents share semantically similar beliefs (via pgvector cosine similarity), they can be promoted to group/org level
- Background Jobs: async operations (PBD, sync, consensus, avatar generation) tracked in background_jobs table with real-time progress polling. Auto-recovery of interrupted jobs on server restart. Jobs page at /[orgSlug]/jobs.
- Charts & Visualizations: recharts-based radar charts (soul/responsibility distribution), diversity bars, platform donut chart, content by agent bar chart, stacked bar chart (content by platform per day), cumulative line graph (identity growth), PBD discovery pipeline funnel (content → observations → signals → beliefs), agent identity timeline, job activity sparkline (14d completed/failed with success rate), belief category donut, source sync health indicators (green/yellow/red dots). Auto-scaling resolution.
- Bootstrap: import agent definitions from open-source repos via vector similarity + Claude

## PBD Pipeline (Pattern-Based Discovery)

The PBD pipeline is the core evolution mechanism. It discovers both beliefs AND responsibilities from content. It works in 3 stages:

1. **Observe**: Import agent content (GitHub commits, website pages, tweets, conversations, etc.) via content sources. Each piece of content becomes a content_item.
2. **Extract**: POST /api/v1/pbd/process triggers analysis. The pipeline reads unprocessed content items, uses Claude to extract behavioral observations (identity patterns + accountability patterns), and clusters similar observations into signals with n-counts and stability scores.
3. **Promote**: Signals that cross the agent's promotion threshold are classified as either a belief or responsibility and promoted to the appropriate table. Promoted items include full provenance.

Trigger PBD manually via POST /api/v1/pbd/process (returns jobId for progress polling), or it runs automatically via the hourly cron sync when new content is imported. Supports org-level processing (pass orgId/orgSlug to process all agents, returns array of {agentId, jobId}).

PBD uses Haiku 4.5 for extraction and promotion, Sonnet 4.6 for clustering. Dynamic batch sizing based on content token estimates. Sequential processing with 2-minute timeout per batch. Failed batches retry as individual items. Config in src/lib/pbd/config.ts.

Key endpoints:
- GET /api/v1/observations?agentId=... — view extracted observations
- GET /api/v1/signals?agentId=... — view clustered signals with n-counts (predict_category=true for AI category prediction)
- POST /api/v1/pbd/process — trigger pipeline for an agent or org (returns jobId(s))
- GET /api/v1/pbd/stats?orgSlug=...&agentId=... — PBD quality metrics: discovery funnel, approval rates, dedup stats, category distribution, job performance. Optional `since` param for time-windowed metrics.
- GET /api/v1/jobs/{jobId} — poll for progress (progress_current/progress_total)
- GET /api/v1/jobs?agentId=...&status=running — list active jobs

## Quick Start

1. POST /api/v1/register — create account + org + API key in one call (zero fields required)
2. Use the returned `your_token` as Authorization: Bearer ln_...
3. POST /api/v1/agents — create an agent (with orgId, name)
4. POST /api/v1/beliefs — add beliefs to define the agent's soul
5. POST /api/v1/responsibilities — add responsibilities
6. POST /api/v1/agents/{agentId}/regenerate-prompt — see the generated system prompt
7. GET /api/v1/agents/{agentId}/files?type=agent — download full agent profile as markdown

## Endpoints

### Registration & Account
- POST   /api/v1/register                               — Create account + org + API key (no auth, zero fields required, returns your_token)
- GET    /api/v1/account                                 — Get account details (auth required)
- PATCH  /api/v1/account                                 — Update email/password/display_name (auth required)

### Agents
- GET    /api/v1/agents                              — List agents (orgId required, groupId optional, include=beliefs,responsibilities, limit/offset)
- GET    /api/v1/agents/{agentId}                     — Get agent with beliefs, responsibilities, group
- POST   /api/v1/agents                              — Create agent (orgId, name required)
- PATCH  /api/v1/agents/{agentId}                     — Update agent
- DELETE /api/v1/agents/{agentId}                     — Delete agent
- PATCH  /api/v1/agents/bulk                          — Update up to 50 agents at once (id, name?, location?, timezone?, jobTitle?)
- GET    /api/v1/agents/{agentId}/diff?since=DATE     — Beliefs/responsibilities added/modified since date
- GET    /api/v1/agents/{agentId}/models              — List agent model assignments (limit/offset, tier filter)
- POST   /api/v1/agents/{agentId}/models              — Assign model to agent (environmentId, modelId required; tier optional — e.g. "planner", "worker", "reviewer")
- DELETE /api/v1/agents/{agentId}/models?environmentId=...&modelId=...&tier=...  — Remove model from agent (tier optional)
- POST   /api/v1/agents/{agentId}/regenerate-prompt   — Regenerate system prompt
- GET    /api/v1/agents/{agentId}/files               — Get agent files (type: agent|soul|responsibilities|identity)
- GET    /api/v1/agents/{agentId}/snapshots             — List genome snapshots (limit/offset)
- POST   /api/v1/agents/{agentId}/snapshots             — Create genome snapshot (optional label)
- GET    /api/v1/agents/{agentId}/snapshots/{snapshotId} — Get snapshot with full genome
- GET    /api/v1/agents/{agentId}/snapshots/diff         — Compare two snapshots (query: a, b)
- POST   /api/v1/agents/{agentId}/responsibility-gaps    — Detect gaps and get AI suggestions
- POST   /api/v1/agents/{agentId}/dynamic-prompt          — Generate randomized prompt variant (optional seed, config override). format="claude_md" generates a natural CLAUDE.md file from the agent's identity.
- POST   /api/v1/agents/{agentId}/import-claude-md        — Parse a CLAUDE.md file into structured beliefs/responsibilities. dryRun=true for preview. Deduplicates against existing items.
- GET    /api/v1/agents/{agentId}/resolved-identity        — Merged org + group + agent identity with source attribution
- GET    /api/v1/agents/{agentId}/overrides                — List agent overrides for inherited items
- POST   /api/v1/agents/{agentId}/overrides                — Hide inherited item (sourceType, sourceId required)
- DELETE /api/v1/agents/{agentId}/overrides/{overrideId}   — Remove override (re-inherit)

### Beliefs (Soul)
- GET    /api/v1/beliefs                   — List beliefs (agentId or groupId required, category/status/starred/hidden optional, limit/offset). groupId returns beliefs from all agents with agent name attribution
- POST   /api/v1/beliefs                   — Create belief (agentId, category, statement required)
- PATCH  /api/v1/beliefs/{beliefId}        — Update belief
- DELETE /api/v1/beliefs/{beliefId}        — Delete belief
- POST   /api/v1/beliefs/{beliefId}/star   — Toggle starred
- POST   /api/v1/beliefs/{beliefId}/hide   — Toggle hidden
- POST   /api/v1/beliefs/bulk              — Create up to 100 beliefs at once (agentId, beliefs: [{category, statement}])
- PATCH  /api/v1/beliefs/bulk              — Bulk star/hide/approve (ids: [...], updates: {starred?, hidden?, status?})

Categories: axiom, principle, voice, preference, boundary
Deduplication: unique on (agent_id, category, statement) — duplicates return 409
Side effects: creating/updating/hiding/deleting beliefs regenerates the agent's system prompt

### Responsibilities
- GET    /api/v1/responsibilities                            — List (agentId required, category/status/starred/hidden optional, limit/offset)
- POST   /api/v1/responsibilities                            — Create (agentId, category, statement required)
- PATCH  /api/v1/responsibilities/{responsibilityId}         — Update
- DELETE /api/v1/responsibilities/{responsibilityId}         — Delete
- POST   /api/v1/responsibilities/{responsibilityId}/star    — Toggle starred
- POST   /api/v1/responsibilities/{responsibilityId}/hide    — Toggle hidden
- POST   /api/v1/responsibilities/bulk                       — Create up to 100 at once (agentId, responsibilities: [{category, statement}])
- PATCH  /api/v1/responsibilities/bulk                       — Bulk star/hide/approve (ids: [...], updates: {starred?, hidden?, status?})

Categories: ownership, execution, collaboration, deliverables, monitoring
Deduplication: unique on (agent_id, category, statement) — duplicates return 409
Side effects: same prompt regeneration as beliefs

### Org Beliefs (Brand Identity)
- GET    /api/v1/organizations/{orgId}/beliefs                         — List (category/status/starred/hidden, limit/offset)
- POST   /api/v1/organizations/{orgId}/beliefs                         — Create (category, statement required)
- PATCH  /api/v1/organizations/{orgId}/beliefs/{beliefId}              — Update
- DELETE /api/v1/organizations/{orgId}/beliefs/{beliefId}              — Delete
- POST   /api/v1/organizations/{orgId}/beliefs/{beliefId}/star         — Toggle starred
- POST   /api/v1/organizations/{orgId}/beliefs/{beliefId}/hide         — Toggle hidden

Same categories as agent beliefs. Cascades prompt regen to ALL agents in org.

### Org Responsibilities (Brand Accountabilities)
- GET    /api/v1/organizations/{orgId}/responsibilities                               — List
- POST   /api/v1/organizations/{orgId}/responsibilities                               — Create
- PATCH  /api/v1/organizations/{orgId}/responsibilities/{responsibilityId}             — Update
- DELETE /api/v1/organizations/{orgId}/responsibilities/{responsibilityId}             — Delete
- POST   /api/v1/organizations/{orgId}/responsibilities/{responsibilityId}/star        — Toggle starred
- POST   /api/v1/organizations/{orgId}/responsibilities/{responsibilityId}/hide        — Toggle hidden

### Group Beliefs (Team Identity)
- GET    /api/v1/groups/{groupId}/beliefs                         — List
- POST   /api/v1/groups/{groupId}/beliefs                         — Create
- PATCH  /api/v1/groups/{groupId}/beliefs/{beliefId}              — Update
- DELETE /api/v1/groups/{groupId}/beliefs/{beliefId}              — Delete
- POST   /api/v1/groups/{groupId}/beliefs/{beliefId}/star         — Toggle starred
- POST   /api/v1/groups/{groupId}/beliefs/{beliefId}/hide         — Toggle hidden

Cascades prompt regen to agents in that group only.

### Group Responsibilities (Team Accountabilities)
- GET    /api/v1/groups/{groupId}/responsibilities                               — List
- POST   /api/v1/groups/{groupId}/responsibilities                               — Create
- PATCH  /api/v1/groups/{groupId}/responsibilities/{responsibilityId}             — Update
- DELETE /api/v1/groups/{groupId}/responsibilities/{responsibilityId}             — Delete
- POST   /api/v1/groups/{groupId}/responsibilities/{responsibilityId}/star        — Toggle starred
- POST   /api/v1/groups/{groupId}/responsibilities/{responsibilityId}/hide        — Toggle hidden

### Agent Overrides
- GET    /api/v1/agents/{agentId}/overrides                    — List overrides
- POST   /api/v1/agents/{agentId}/overrides                    — Hide inherited item (sourceType, sourceId required)
- DELETE /api/v1/agents/{agentId}/overrides/{overrideId}       — Remove override (re-inherit)

sourceType: org_belief, group_belief, org_responsibility, group_responsibility

### Resolved Identity
- GET /api/v1/agents/{agentId}/resolved-identity — Merged org + group + agent identity with source attribution and summary stats

### Consensus Detection
- POST /api/v1/organizations/{orgId}/consensus  — Detect shared beliefs/responsibilities across all agents in org
- POST /api/v1/groups/{groupId}/consensus       — Detect shared beliefs/responsibilities across agents in group

Returns: { beliefs_created, beliefs_skipped, responsibilities_created, responsibilities_skipped, details }

### Background Jobs
- GET /api/v1/jobs                — List jobs (agentId, orgId, status filters, last 24h)
- GET /api/v1/jobs/{jobId}        — Get job status with progress

Job types: pbd, sync, consensus, backfill
Status: queued → running → completed | failed
Progress: progress_current / progress_total updated in real-time

### Embedding Backfill
- POST /api/v1/beliefs/backfill-embeddings — Generate embeddings for all beliefs/responsibilities missing them (orgId required)

### Organizations
- GET    /api/v1/organizations                     — List user's organizations with roles
- POST   /api/v1/organizations                     — Create org (name, slug required)
- PATCH  /api/v1/organizations/{orgId}              — Update org settings (incl. auto_promote_shared_beliefs, consensus_similarity_threshold, consensus_agent_percentage)
- DELETE /api/v1/organizations/{orgId}              — Hard delete with cascade (requires owner role, session auth, body: {confirmSlug})
- GET    /api/v1/organizations/{orgId}/summary      — Full org overview: groups, agents (with belief/resp counts), content sources, content items
- GET    /api/v1/organizations/{orgId}/members      — List org members with roles (id, role, user_id, profiles)

### API Keys
- GET    /api/v1/organizations/{orgId}/api-keys           — List keys (metadata only, session auth)
- POST   /api/v1/organizations/{orgId}/api-keys           — Create key (returns raw key once, session auth)
- DELETE /api/v1/organizations/{orgId}/api-keys/{keyId}   — Revoke key (session auth)

### Groups
- GET    /api/v1/groups             — List groups with agent_count, pagination (orgId/orgSlug required)
- POST   /api/v1/groups             — Create group (orgId, name required)
- PATCH  /api/v1/groups/{groupId}   — Update group
- DELETE /api/v1/groups/{groupId}   — Delete group

### Models
- GET    /api/v1/models             — List models (orgId required, limit/offset)
- POST   /api/v1/models             — Create model (orgId, provider, modelId, name required)
- PATCH  /api/v1/models/{modelId}   — Update model
- DELETE /api/v1/models/{modelId}   — Delete model

### Environments
- GET    /api/v1/environments                          — List environments (orgId required, limit/offset)
- POST   /api/v1/environments                          — Create environment
- PATCH  /api/v1/environments/{environmentId}          — Update environment
- DELETE /api/v1/environments/{environmentId}          — Delete environment
- GET    /api/v1/environments/{environmentId}/models   — List env models
- POST   /api/v1/environments/{environmentId}/models   — Add model to env
- DELETE /api/v1/environments/{environmentId}/models   — Remove model from env

### Conversations
- GET    /api/v1/conversations                              — List sessions (agentId required, limit/offset)
- POST   /api/v1/conversations                              — Create session with participants
- GET    /api/v1/conversations/{sessionId}                   — Get full session with messages
- PATCH  /api/v1/conversations/{sessionId}                   — Update session. Set status="completed" to trigger auto-publish if org has auto_publish_conversations=true. Auto-publish creates content_items for each agent participant and triggers PBD automatically.
- POST   /api/v1/conversations/{sessionId}/messages          — Add messages
- POST   /api/v1/conversations/{sessionId}/publish           — Publish as content
- DELETE /api/v1/conversations/{sessionId}/publish           — Unpublish
- POST   /api/v1/conversations/format                        — Format raw transcript via LLM

### Content
- GET   /api/v1/content-items                           — List items (agentId required, sourceType filter: github_commit/github_file/tweet/substack_post/conversation, supports limit/offset)
- PATCH /api/v1/content-items/{itemId}                  — Update status (imported or hidden)
- GET   /api/v1/content-sources                         — List sources (agentId or orgId required)
- POST  /api/v1/content-sources                         — Create source (platform: github, website, twitter, rss, or linkedin; agentId required)
- GET   /api/v1/content-sources/{sourceId}              — Get source
- PATCH /api/v1/content-sources/{sourceId}              — Update source (config, enabled, name, agentId, githubConnectionId, xConnectionId)
- DELETE /api/v1/content-sources/{sourceId}             — Delete source
- POST  /api/v1/content-sources/{sourceId}/sync         — Sync source (GitHub commits, website pages, Twitter tweets, RSS entries, or LinkedIn data)

### GitHub Connections
- GET    /api/v1/github/connections                     — List connections (orgId required, never exposes token)
- POST   /api/v1/github/connections                     — Create from PAT (orgId, token required)
- GET    /api/v1/github/connections/{connectionId}      — Get connection details + usage count
- DELETE /api/v1/github/connections/{connectionId}      — Delete connection (nullifies FK on sources)
- GET    /api/v1/github/oauth/authorize                 — Start OAuth flow (orgId, redirect params)
- GET    /api/v1/github/oauth/callback                  — OAuth callback (code, state params)
- GET    /api/v1/github/repos                           — List repos for a connection (connectionId required)

### X Connections
- GET    /api/v1/x-connections                          — List X connections (orgId required, never exposes credentials)
- POST   /api/v1/x-connections                          — Create connection (orgId, label, xUsername, xUserId, apiKey, apiSecret, accessToken, accessTokenSecret)
- DELETE /api/v1/x-connections                          — Delete connection (id in body)

### LinkedIn Import
- POST /api/v1/linkedin/import — Import LinkedIn data export ZIP (multipart/form-data: file + orgId/orgSlug + agentId required). Creates content_items with platform "linkedin" (source_types: linkedin_profile, linkedin_post, linkedin_article). Returns source_id, profile_data, posts/articles imported counts.

### Observations & Signals (read-only, generated by PBD)
- GET /api/v1/observations   — List observations (agentId required, limit default 100)
- GET /api/v1/signals        — List signals (agentId required, predict_category=true for AI category prediction, promoted=false checks both belief and responsibility promotion)

### Bootstrap
- POST /api/v1/bootstrap/scrape      — Scrape repos and decompose (standard auth, heavy operation)
- POST /api/v1/bootstrap/recommend   — Get tailored recommendations for an agent
- POST /api/v1/bootstrap/apply       — Batch upsert beliefs/responsibilities (updates nCount/status on existing, optional status/nCount)

### Dedup & Merge
- POST /api/v1/agents/{agentId}/dedup         — Scan agent beliefs/responsibilities for semantic duplicates. LLM merges clusters into best single statement. dryRun=true (default) previews, dryRun=false merges.
- POST /api/v1/organizations/{orgId}/dedup    — Same for org-level beliefs/responsibilities

### Cron
- POST /api/v1/cron/sync-sources    — Auto-sync stale sources + trigger PBD (CRON_SECRET auth, not Supabase)
- POST /api/v1/cron/consensus       — Nightly consensus detection for all orgs (CRON_SECRET auth). Each org runs during an assigned hour (9pm-6am PST) based on hash of org ID. Requires 2+ agents.
- POST /api/v1/cron/dedup           — Nightly dedup/merge for all orgs + agents (CRON_SECRET auth). Clusters semantically similar beliefs/responsibilities, LLM synthesizes best statement, deletes redundants. Staggered by org.

### Utility
- POST /api/v1/pbd/process      — Trigger PBD for an agent (agentId) or org (orgId/orgSlug). Returns jobId(s) (async, 202)
- GET  /api/v1/pbd/stats         — PBD quality metrics (orgSlug/orgId required, optional agentId, since). Returns discovery funnel, approval rates, dedup stats, category distribution, job performance
- GET  /api/v1/github/tree       — Browse GitHub repo file/folder structure (owner, repo required. connectionId for private repos, mode=full returns importable files+folders capped at 5000 items)

## Error Format

All errors: { "error": "message" }
Status codes: 400 (bad request), 401 (unauthorized), 404 (not found), 409 (conflict), 500 (server error)

## Key Behaviors

- SSRF protection: all user-provided URLs validated — private IPs, cloud metadata, internal hostnames, and non-HTTP protocols are blocked at source creation and every fetch
- Prompt regeneration: triggered automatically when beliefs/responsibilities/name/description/job title/location/timezone change
- Status flow: beliefs and responsibilities have pending/approved/rejected status
- Multi-tenancy: all data scoped by org_id via row-level security
- Pagination: all list endpoints return { data: [...], count } with limit/offset params
- HATEOAS: all success responses include next_steps array with suggested follow-up actions
- Background jobs: PBD discovery, content sync, consensus detection, avatar generation all tracked in background_jobs table. Poll GET /api/v1/jobs/{jobId} for progress. Avatar generation returns avatarJobId from PATCH /api/agents/{id}. Jobs page at /[orgSlug]/jobs with live polling, ETA, stop/re-run. Auto-recovery of interrupted jobs on server restart.
- Bulk operations: PATCH /api/v1/agents/bulk (50 max), POST /api/v1/beliefs/bulk (100 max), PATCH /api/v1/beliefs/bulk, POST /api/v1/responsibilities/bulk (100 max), PATCH /api/v1/responsibilities/bulk, POST /api/v1/bootstrap/apply (batch upserts, updates existing on conflict)
- Text normalization: all belief/responsibility statements are normalized (curly quotes → straight, em-dashes → hyphens) to prevent Unicode near-duplicates
- Semantic dedup: all belief/responsibility creation (agent, org, group, PBD promotion) checks for semantic duplicates before inserting. Three tiers: >85% cosine similarity = auto-merge (increment n_count), 65-85% = LLM judges "same core idea?", <65% = new. Deduped responses return 200 with _deduplicated: true and _matched_similarity. Also backfills missing embeddings on existing items.
- Content source config (github): import_commits=true, import_files=false by default. File import uses an allowlist -- only prose/documentation files are imported (.md, .mdx, .txt, .rst, .adoc, .org, .tex, plus README/LICENSE/CHANGELOG/CONTRIBUTING/CODE_OF_CONDUCT/SECURITY/AUTHORS/CLAUDE.md). Code files excluded. Max 50KB per file. include_paths config selects specific folders (path ending /) or files. Use GET /api/v1/github/tree?mode=full to browse importable files.
- Content source config (website): discovery modes — llms_txt (reads /llms.txt), sitemap (parses /sitemap.xml), manual (explicit URL list). Supports domain, url_pattern, max_pages, extract_mode (article/full/markdown)
- Content source config (twitter): username required, exclude_retweets=true, exclude_replies=true, max_pages=3 (100 tweets/page) by default. Requires xConnectionId with OAuth 1.0a credentials.
- Content source config (rss): feed_url required, max_entries=50, sync_interval_hours=24 by default. No connection required — RSS feeds are public. Works with any RSS 2.0 or Atom feed (Substack, Medium, WordPress, etc.). Content items created with platform "rss", source_type "rss_entry".
- Content source config (linkedin): user uploads LinkedIn data export ZIP via POST /api/v1/linkedin/import (multipart/form-data). Parses Profile.csv, Positions.csv, Education.csv, Skills.csv, Shares.csv, and Articles/ HTML files. No API key or OAuth needed. Content items created with platform "linkedin", source_types: linkedin_profile, linkedin_post, linkedin_article.
- Content sources require agent association (agentId required) — PBD needs agent_id to process content
- GitHub connections: per-user OAuth or PAT tokens, encrypted with AES-256-GCM, used for private repo access
- X connections: OAuth 1.0a credentials (API key, API secret, access token, access token secret), encrypted with AES-256-GCM. X API allows 100 reads/month per app.
- Commit attribution: agents have optional github_username field — during sync, commits are matched by author login to the correct agent in the org (unmatched commits fall back to the source's default agent)
- Sync returns affected_agent_ids — all agents that received content get PBD triggered, not just the source owner
- Auto-sync: cron endpoint syncs stale sources hourly and triggers PBD for agents with new content. Cron response includes rss_entries_imported field. RSS sources default to 24h sync interval.
- Scope-aware operations: PATCH and DELETE on /api/v1/beliefs/{id} and /api/v1/responsibilities/{id} automatically detect whether the item is agent-level, group-level, or org-level. No need to use scope-specific endpoints for updates or deletes.
- PBD hide-on-delete: DELETE on beliefs/responsibilities that were discovered by PBD will hide them instead of deleting, preserving discovery history. Returns { action: "hidden", reason: "..." } for PBD items, { action: "deleted", scope: "agent"|"group"|"org" } for manual items.
- Cross-scope bulk updates: PATCH /api/v1/beliefs/bulk and PATCH /api/v1/responsibilities/bulk work across agent, group, AND org scopes in one call. Response includes agents_affected, groups_affected, orgs_affected counts.
- Cascading prompt regeneration: org belief changes regen all agents in org, group belief changes regen agents in group
- Deduplication: if agent has same (category, statement) as org/group, agent version wins
- Agent overrides: agents can hide inherited beliefs without deleting them from the org/group
- Admin dashboard: super-admin only (session auth, hardcoded emails). Pages: Overview (stat cards with trend indicators, PBD pipeline funnel), Trends (time-series charts with 24h/7d/30d/90d range selector), Health (10 automated checks with score ring), Organizations (searchable table with per-org drill-down), Users (all users with memberships), Usage (job stats, API key activity, content by platform, recent failures)

### Admin API (super-admin session auth only, no API key support)
- GET /api/v1/admin/stats — platform-wide aggregate counts + 7d activity
- GET /api/v1/admin/organizations — all orgs with member/agent/key counts (limit/offset/search)
- GET /api/v1/admin/users — all users with emails, memberships, last sign-in (limit/offset/search)
- GET /api/v1/admin/usage — API key activity, job stats by type, content by platform, failures (days param)
- GET /api/v1/admin/trends — daily time-series for users, agents, jobs, content, beliefs (days param)
- GET /api/v1/admin/health — 10 automated health checks with severity, recommendations, and overall score