Live Neon API Reference

AI talent management platform. Create and manage AI agents with structured identities (soul) and accountabilities (responsibilities) that combine into generated system prompts.

Base URL: https://agent.liveneon.ai

API Status: This API is unversioned and under active development. Breaking changes are possible. No formal changelog is maintained yet — monitor the GitHub repository for changes.

Authentication

All endpoints require a Supabase bearer token in the Authorization header.

Authorization: Bearer <supabase-access-token>

To get a token, authenticate via Supabase Auth (email/password, OAuth, etc.) and use the returned access_token. The token is a JWT that encodes your user ID and org memberships.

# Example: Authenticate and get a token
curl -X POST 'https://tnkjbyhumicerkluqrxi.supabase.co/auth/v1/token?grant_type=password' \
  -H 'apikey: <supabase-anon-key>' \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "password": "your-password"}'

# Use the access_token from the response
export TOKEN="<access_token from response>"

Error (401):

{ "error": "Unauthorized" }

Rate Limiting

There are currently no rate limits enforced on any endpoint. This will change as the platform matures. Please be respectful with request volume — excessive automated requests may be throttled without notice in the future.

Core Concepts

Organizations

Multi-tenant isolation. Every resource belongs to an org_id. Users are members of organizations via org_memberships. URLs use slug-based routing (/[orgSlug]/...).

Agents

Virtual talent with structured identities. Each agent has a name, job title, description, optional group membership, and a generated system prompt built from their soul and responsibilities.

Note: There is currently no GET /api/agents (list all agents) or GET /api/agents/{agentId} (get single agent) endpoint. Agents are accessed through the dashboard UI. To work with a specific agent via the API, you need to know its agentId (UUID). You can find agent IDs in the dashboard URL when viewing an agent, or by querying the Supabase database directly. These listing endpoints are planned for a future release.

Soul (Beliefs)

An agent's identity — what they believe, how they speak, what they won't do. Beliefs belong to one of 5 categories:

• axiom — foundational truths
• principle — guiding rules
• voice — communication style
• preference — tendencies and defaults
• boundary — lines they won't cross

Responsibilities

What an agent is accountable for. 5 categories:

• ownership — what they own
• execution — how they get things done
• collaboration — how they work with others
• deliverables — what they produce
• monitoring — what they watch

System Prompt

Generated markdown combining soul + responsibilities + location/timezone. Cached on the agent record. Automatically regenerated when beliefs, responsibilities, location, or timezone change.

Groups

Organizational groupings for agents (e.g., "Marketing Team"). Groups can have a manager agent (must be from a different group).

Environments & Models

Environments represent deployment contexts (e.g., "production", "staging"). Models are LLM configurations (provider + model ID). Agents are assigned models per environment.

Pattern-Based Discovery (PBD)

The platform's core innovation. PBD is a three-stage AI pipeline that observes agent outputs and discovers identity patterns: (1) extract observations from content, (2) cluster into recurring signals, (3) promote stable signals to proposed beliefs. Observations and signals are read-only via the API — they are generated exclusively by the PBD pipeline.

Bootstrap

Import agent definitions from open-source repos. The pipeline scrapes repos, decomposes agent prompts into structured beliefs/responsibilities via Claude, stores them with vector embeddings, and recommends them to agents via similarity search.

Agents

Create Agent

POST /api/agents

Request Body:

Response (201):

{
  "id": "uuid",
  "org_id": "uuid",
  "name": "Content Director",
  "description": "...",
  "group_id": "uuid",
  "job_title": "Content Director",
  "identity_markers": ["creative", "strategic"],
  "system_prompt": null,
  "avatar_url": null,
  "location": null,
  "timezone": null,
  "created_at": "2026-03-12T...",
  "updated_at": "2026-03-12T..."
}

Example:

curl -X POST https://agent.liveneon.ai/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orgId": "your-org-id", "name": "Content Director", "jobTitle": "Content Director"}'

Errors: 400 (missing orgId or name), 500 (database error)

Update Agent

PATCH /api/agents/{agentId}

Request Body (all optional):

Response (200): Updated agent object.

Side effects: Regenerates system prompt if location, timezone, or jobTitle changed. Triggers avatar generation if avatarPrompt provided.

Example:

curl -X PATCH https://agent.liveneon.ai/api/agents/{agentId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"location": "San Francisco, CA", "timezone": "America/Los_Angeles"}'

Errors: 404 (not found), 500 (database error)

Delete Agent

DELETE /api/agents/{agentId}

Response (200):

{ "success": true }

Get Agent Models

GET /api/agents/{agentId}/models

Response (200): Array of agent_environment_models with expanded environment and model objects.

[
  {
    "id": "uuid",
    "agent_id": "uuid",
    "environment_id": "uuid",
    "model_id": "uuid",
    "is_primary": true,
    "environments": { "id": "uuid", "name": "Production", "slug": "production" },
    "models": { "id": "uuid", "provider": "anthropic", "model_id": "claude-sonnet-4-20250514", "name": "Claude Sonnet" }
  }
]

Add Agent Model

POST /api/agents/{agentId}/models

Request Body:

Response (201): Created agent_environment_models record.

Errors: 400 (missing fields), 409 (duplicate assignment)

Remove Agent Model

DELETE /api/agents/{agentId}/models

Note: This DELETE endpoint requires a JSON request body. Some HTTP clients (e.g., older versions of curl, certain API gateways) may not send bodies with DELETE requests. If you encounter issues, ensure your client supports this pattern.

Request Body:

Response (200): { "success": true }

Regenerate System Prompt

POST /api/agents/{agentId}/regenerate-prompt

Forces regeneration of the agent's system prompt from current beliefs and responsibilities.

Example:

curl -X POST https://agent.liveneon.ai/api/agents/{agentId}/regenerate-prompt \
  -H "Authorization: Bearer $TOKEN"

Response (200):

{ "systemPrompt": "# Agent Name\n\nYou are..." }

Errors: 404 (agent not found)

Get Agent Files

GET /api/agents/{agentId}/files

Returns agent data as downloadable markdown files.

Query Parameters:

Response (200): Content-Type: text/markdown — rendered markdown content.

Errors: 400 (invalid type), 404 (agent not found)

Beliefs

Create Belief

POST /api/beliefs

Request Body:

Response (201): Created belief object.

Side effects: Creates belief_sources record if sourceType provided. Regenerates agent system prompt.

Example:

curl -X POST https://agent.liveneon.ai/api/beliefs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent-uuid", "category": "principle", "statement": "Always prioritize clarity over cleverness"}'

Errors: 400 (missing required fields), 404 (agent not found)

Update Belief

PATCH /api/beliefs/{beliefId}

Request Body (all optional):

Response (200): Updated belief object.

Side effects:

• status: "approved" → sets approved_by to current user, hidden to false
• status: "rejected" → sets hidden to true
• Regenerates prompt if status changed

Delete Belief

DELETE /api/beliefs/{beliefId}

Response (200): { "success": true }

Side effects: Regenerates agent system prompt.

Toggle Belief Star

POST /api/beliefs/{beliefId}/star

Toggles the starred flag. Starred beliefs are emphasized in the system prompt.

Response (200): Updated belief with toggled starred value.

Toggle Belief Hide

POST /api/beliefs/{beliefId}/hide

Toggles the hidden flag. Hidden beliefs are excluded from the system prompt.

Response (200): Updated belief with toggled hidden value.

Side effects: Regenerates agent system prompt.

Responsibilities

Create Responsibility

POST /api/responsibilities

Request Body:

Response (201): Created responsibility object.

Side effects: Regenerates agent system prompt.

Example:

curl -X POST https://agent.liveneon.ai/api/responsibilities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent-uuid", "category": "ownership", "statement": "Own the content calendar and publishing pipeline"}'

Errors: 400 (missing required fields), 404 (agent not found)

Update Responsibility

PATCH /api/responsibilities/{responsibilityId}

Request Body (all optional):

Response (200): Updated responsibility object.

Side effects: Same approval/rejection logic as beliefs. Regenerates prompt if status changed.

Delete Responsibility

DELETE /api/responsibilities/{responsibilityId}

Response (200): { "success": true }

Side effects: Regenerates agent system prompt.

Toggle Responsibility Star

POST /api/responsibilities/{responsibilityId}/star

Response (200): Updated responsibility with toggled starred value.

Toggle Responsibility Hide

POST /api/responsibilities/{responsibilityId}/hide

Response (200): Updated responsibility with toggled hidden value.

Side effects: Regenerates agent system prompt.

Organizations

Create Organization

POST /api/organizations

Request Body:

Response (201): Organization object. The creating user is automatically added as owner via database trigger.

Example:

curl -X POST https://agent.liveneon.ai/api/organizations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Company", "slug": "my-company"}'

Errors: 409 (slug already exists)

Update Organization

PATCH /api/organizations/{orgId}

Request Body (all optional):

Response (200): Updated organization object.

Errors: 400 (empty name or no valid fields)

Groups

List Groups

GET /api/groups

Query Parameters:

Example:

curl https://agent.liveneon.ai/api/groups?orgId=your-org-id \
  -H "Authorization: Bearer $TOKEN"

Response (200): Array of group objects ordered by display_order, name.

Create Group

POST /api/groups

Request Body:

Response (201): Created group object.

Update Group

PATCH /api/groups/{groupId}

Request Body (all optional):

Response (200): Updated group object.

Errors: 400 (manager agent not found or from same group)

Delete Group

DELETE /api/groups/{groupId}

Response (200): { "success": true }

Models

List Models

GET /api/models

Query Parameters:

Response (200): Array of model objects ordered by provider, name.

[
  {
    "id": "uuid",
    "org_id": "uuid",
    "provider": "anthropic",
    "model_id": "claude-sonnet-4-20250514",
    "name": "Claude Sonnet",
    "provider_url": "https://api.anthropic.com",
    "description": "Fast, capable model"
  }
]

Create Model

POST /api/models

Request Body:

Response (201): Created model object.

Errors: 409 (duplicate provider + modelId combination)

Update Model

PATCH /api/models/{modelId}

Request Body (all optional): provider, modelId, name, providerUrl, description

Response (200): Updated model object.

Delete Model

DELETE /api/models/{modelId}

Response (200): { "success": true }

Environments

List Environments

GET /api/environments

Query Parameters:

Response (200): Array of environment objects ordered by display_order, created_at.

Create Environment

POST /api/environments

Request Body:

Response (201): Created environment object.

Errors: 409 (duplicate slug)

Update Environment

PATCH /api/environments/{environmentId}

Request Body (all optional): name, slug, description, isDefault, displayOrder

Response (200): Updated environment object.

Delete Environment

DELETE /api/environments/{environmentId}

Response (200): { "success": true }

List Environment Models

GET /api/environments/{environmentId}/models

Response (200): Array of environment_models with expanded model objects.

Add Model to Environment

POST /api/environments/{environmentId}/models

Request Body:

Response (201): Created environment_models record.

Errors: 409 (duplicate)

Remove Model from Environment

DELETE /api/environments/{environmentId}/models

Note: This DELETE endpoint requires a JSON request body. See the note on Remove Agent Model for client compatibility considerations.

Request Body:

Response (200): { "success": true }

Conversations

Terminology note: The API URLs use "conversations" and route params use sessionId. The underlying database table is conversation_sessions. These terms are interchangeable — a conversation is a session. Response objects use the database column names (e.g., started_at, ended_at).

List Conversations

GET /api/conversations

Query Parameters:

Example:

curl https://agent.liveneon.ai/api/conversations?agentId=agent-uuid \
  -H "Authorization: Bearer $TOKEN"

Response (200):

{
  "data": [
    {
      "id": "uuid",
      "org_id": "uuid",
      "title": "Strategy Discussion",
      "status": "active",
      "started_at": "2026-03-12T...",
      "participant_count": 2,
      "message_count": 15
    }
  ],
  "count": 1
}

Sessions are ordered by started_at descending and enriched with computed participant_count and message_count.

Create Conversation

POST /api/conversations

Request Body:

Participant object:

Response (201): Session object with participants array.

Get Conversation

GET /api/conversations/{sessionId}

Response (200): Full session object including participants and messages arrays.

Errors: 404 (not found)

Update Conversation

PATCH /api/conversations/{sessionId}

Request Body (all optional):

Response (200): Updated session object.

Side effects: If status: "completed" and org has auto_publish_conversations enabled, auto-publishes to content_items.

Add Messages

POST /api/conversations/{sessionId}/messages

Supports three modes:

Mode 1 — Single message:

Mode 2 — Batch messages:

Each message: { participantId, content, metadata }

Mode 3 — Format raw transcript:

Response (201): Array of inserted messages with auto-incremented sequence_number.

Publish Conversation

POST /api/conversations/{sessionId}/publish

Creates a content_item from the conversation for a specific agent.

Request Body:

Response (201): Content item object.

Side effects: Marks session as published. Triggers PBD (principle-based distillation) pipeline in background.

Unpublish Conversation

DELETE /api/conversations/{sessionId}/publish

Query Parameters:

Response (200): { "success": true }

Side effects: Soft-deletes content_items, clears published_at on session.

Format Transcript

POST /api/conversations/format

Uses an LLM to parse raw conversation text into structured messages.

Request Body:

Response (200):

{
  "title": "Strategy Discussion",
  "messages": [
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "..." }
  ]
}

Content Items

List Content Items

GET /api/content-items

Query Parameters:

Response (200):

{ "data": [...], "count": 123 }

Update Content Item

PATCH /api/content-items/{itemId}

Request Body:

Response (200): Updated content_item object.

Content Sources

List Content Sources

GET /api/content-sources

Query Parameters:

Response (200): Array of content_sources ordered by created_at descending.

Create Content Source

POST /api/content-sources

Request Body:

Config object (for platform: "github"):

Response (201): Created content_sources record.

Get Content Source

GET /api/content-sources/{sourceId}

Response (200): Content source object.

Update Content Source

PATCH /api/content-sources/{sourceId}

Request Body (all optional): config, enabled

Response (200): Updated content source.

Delete Content Source

DELETE /api/content-sources/{sourceId}

Response (200): { "success": true }

Sync Content Source

POST /api/content-sources/{sourceId}/sync

Triggers a sync of the content source (fetches latest data from GitHub).

Response (200): Sync result object.

Side effects: Triggers PBD pipeline for the agent in background.

Errors: 404 (source not found), 400 (source disabled or unsupported platform)

Observations

Observations are read-only. They are generated exclusively by the PBD pipeline when content is processed — there is no endpoint to create, update, or delete observations manually.

List Observations

GET /api/observations

Query Parameters:

Response (200):

{ "data": [...], "count": 42 }

Signals

Signals are read-only. They are clustered from observations by the PBD pipeline. When a signal's reinforcement count crosses the agent's min_n_count threshold, it can be promoted to a belief (this promotion is also handled by the pipeline).

List Signals

GET /api/signals

Query Parameters:

Response (200):

{ "data": [...], "count": 15 }

Bootstrap

Scrape Repos

POST /api/bootstrap/scrape

Scrapes open-source repos, decomposes agent prompts into structured beliefs/responsibilities via Claude, and stores them with vector embeddings. Requires standard authentication (same bearer token as all other endpoints — there is no separate admin role check). This is a heavy operation that calls Claude and OpenAI APIs, so use sparingly.

Request Body (all optional):

If no owner/repo provided, scrapes all configured repos.

Response (200):

{
  "repos_scraped": 7,
  "templates_created": 42,
  "templates_updated": 5,
  "templates_skipped": 2,
  "errors": []
}

Get Recommendations

POST /api/bootstrap/recommend

Generates tailored belief/responsibility recommendations for an agent based on their profile, using vector similarity search + Claude.

Request Body:

Response (200):

{
  "beliefs": [
    {
      "category": "principle",
      "statement": "Always prioritize clarity over cleverness",
      "confidence": "high",
      "source": "repo-name/agent-name"
    }
  ],
  "responsibilities": [
    {
      "category": "ownership",
      "statement": "Own the content calendar and publishing pipeline",
      "confidence": "medium",
      "source": "repo-name/agent-name"
    }
  ]
}

Apply Recommendations

POST /api/bootstrap/apply

Batch-creates beliefs and/or responsibilities from selected recommendations.

Request Body:

At least one of beliefs or responsibilities must be non-empty.

Response (200):

{
  "beliefsCreated": 5,
  "responsibilitiesCreated": 3
}

Side effects: All created with status: "approved". Regenerates system prompt once after all inserts.

Utility

Process PBD

POST /api/pbd/process

Triggers principle-based distillation for an agent — analyzes their content to extract observations and signals.

Request Body:

Response (202):

{ "status": "processing", "agentId": "uuid" }

Fire-and-forget background job.

GitHub Tree

GET /api/github/tree

Browse a GitHub repo's folder structure.

Query Parameters:

Response (200):

{
  "folders": ["src", "src/lib", "src/app", "docs"],
  "total_files": 142
}

Common Error Responses

All errors follow this shape:

{ "error": "Human-readable error message" }

Key Patterns

Prompt Regeneration

Creating, updating, hiding, or deleting beliefs and responsibilities automatically regenerates the agent's system prompt. The updated prompt is cached on agents.system_prompt.

Status Approval Flow

Beliefs and responsibilities have a status field (pending, approved, rejected). Approving sets approved_by and unhides the item. Rejecting hides it. Organizations can enable auto-approval.

Multi-tenancy

All data is scoped by org_id. Row-level security ensures users only see data from their organizations. The org_id is denormalized on all tables for efficient queries.

Pagination

List endpoints that support pagination return { data: [...], count: number } with limit and offset query parameters. Default limits vary by endpoint:

• Content items: limit=50, offset=0
• Observations: limit=100, offset=0

There are currently no enforced maximum limits — you can request any page size. Use reasonable values (100–500) to avoid large payloads.

Bulk Operations

The only bulk/batch endpoint is POST /api/bootstrap/apply, which batch-creates multiple beliefs and responsibilities in a single request. All other create endpoints handle one resource at a time. If you need to create multiple beliefs or responsibilities outside the bootstrap flow, make individual requests.

Background Jobs & Async Operations

Avatar generation (Leonardo.AI) and PBD processing run as fire-and-forget background jobs. The API returns immediately (201 or 202) while processing continues. There is currently no webhook or callback mechanism to notify you when background jobs complete. To check if an avatar has been generated, poll the agent's avatar_url field. To check PBD results, poll the observations and signals endpoints.

DELETE Requests with Bodies

Some DELETE endpoints (DELETE /api/agents/{agentId}/models, DELETE /api/environments/{environmentId}/models) require a JSON request body. While this is technically valid HTTP, some clients and proxies may not support it. Ensure your HTTP client sends the Content-Type: application/json header and includes the body with DELETE requests.

Response Code Notes

• Most create operations return 201 Created
• POST /api/bootstrap/apply returns 200 OK (not 201) despite creating resources — this is because it's a batch operation that may partially succeed
• POST /api/pbd/process returns 202 Accepted since processing happens in the background

OpenAPI / JSON Schema

A formal OpenAPI specification is not yet available. This markdown document is the canonical API reference. An OpenAPI spec is planned for a future release.