# 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://agent.liveneon.ai/api/v1 (also works without /v1 — both /api/v1/ and /api/ are identical)
Docs: https://agent.liveneon.ai/docs/api
OpenAPI: https://agent.liveneon.ai/openapi.json
Agent Card: https://agent.liveneon.ai/.well-known/agent-card.json

## Authentication

API Keys: Create an org-scoped key in your organization's settings page. 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.

## 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), platform donut chart, content by agent bar chart, stacked bar chart (content by platform per day), cumulative line graph (identity growth). 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/jobs/{jobId} — poll for progress (progress_current/progress_total)
- GET /api/v1/jobs?agentId=...&status=running — list active jobs

## Quick Start

1. Authenticate via Supabase Auth to get a bearer token
2. POST /api/v1/organizations — create an org
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

### 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)
- POST   /api/v1/agents/{agentId}/models              — Assign model to agent
- DELETE /api/v1/agents/{agentId}/models?environmentId=...&modelId=...  — Remove model from agent
- 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)
- 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

### 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
- 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, 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)

### Cron
- POST /api/v1/cron/sync-sources    — Auto-sync stale sources + trigger PBD (CRON_SECRET auth, not Supabase)

### Utility
- POST /api/v1/pbd/process      — Trigger PBD for an agent (agentId) or org (orgId/orgSlug). Returns jobId(s) (async, 202)
- GET  /api/v1/github/tree       — Browse GitHub repo folder structure (optional connectionId for private repos)

## 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
- Content source config (github): import_commits=true, import_files=false by default
- 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