Nexus Documentation & API Reference

Getting Started

Get your first AI-powered development task running in under five minutes.

1. Create your account

Sign up at /portal with your email address. No credit card is required for the free trial. Once signed in you will land on the Command Center dashboard.

2. Connect your first repository

From the Command Center, use the onboarding wizard or run the onboard command via the API:

# Via the API
curl -X POST https://your-nexus-instance/api/onboard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"repo_url": "https://github.com/you/your-repo.git"}'
        

Nexus clones the repository, indexes the codebase, and builds a project context. This typically takes one to three minutes depending on repository size. The indexing process extracts architecture patterns, dependency graphs, and coding conventions so agents understand how your project is structured.

3. Run your first task

Once the repository is onboarded, create a task from the Command Center or via the API:

curl -X POST https://your-nexus-instance/api/tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"description": "Add input validation to the user registration endpoint", "project": "your-repo"}'
        

The task enters the pipeline and flows through the plan, implement, test, review, and PR stages. You can watch progress in real time on the dashboard or receive notifications via Discord and push alerts.

Tip: You can also delegate tasks by calling your AI project manager Rachel on the phone or messaging her on Discord. Just describe what you need in plain language.

Core Concepts

Understanding these concepts will help you get the most out of the platform.

Agents are the AI team members that do the work. Each agent has a specific role (developer, QA engineer, project manager, etc.), a persistent memory, a distinct voice, and configurable autonomy levels.

Agents are not stateless LLM calls. They maintain episodic memory of past conversations and tasks, learn your preferences over time, and build up expertise in your specific codebase. When an agent encounters a problem it has seen before, it recalls the previous solution and adapts it.

The default team includes 10 agents. Enterprise plans allow custom agent roles and personas.

The pipeline is the sequence of stages every task flows through. The default pipeline has five stages:

Plan -- Analyse the task, identify affected files, and produce an implementation plan
Implement -- Write the code changes according to the plan
Test -- Run the test suite and validate the changes
Review -- A separate agent reviews the diff for correctness and quality
PR -- Open a pull request with description, test results, and change summary

You can customise the pipeline in config/pipeline.json. Stages can be skipped, reordered, or have approval gates inserted between them.

Governance controls what agents can do autonomously and what requires human approval. The system uses three autonomy levels:

Read -- Agent can read files and analyse code but cannot make changes
Suggest -- Agent can propose changes but must wait for approval before executing
Execute -- Agent can make changes autonomously within defined constraints

When an agent needs to do something beyond its autonomy level, it creates a proposal. Proposals are sent to you via Discord, push notification, or phone call. You can approve or reject them from any channel. All proposals have a hard cap of 10 active proposals per agent to prevent notification spam.

Destructive operations like deployments and budget expenditure always require explicit approval, even at the Execute autonomy level.

The knowledge base is a vector-searchable store of everything the system has learned. It includes:

Facts -- Extracted from conversations, code reviews, and documentation
Decisions -- Architecture choices and their rationale
Preferences -- Your coding style, naming conventions, and tool choices
Skills -- Reusable patterns and solutions from past tasks

Knowledge is indexed using vector embeddings for semantic search. When an agent starts a new task, it queries the knowledge base for relevant context automatically. You can also add entries manually via the dashboard or API.

Configuration

Nexus is configured through JSON files and environment variables. All configuration can also be managed via the dashboard.

Provider Configuration

AI providers are configured in config/provider-policy.json. This file controls which models are available, their priority order, rate limits, and cost caps.

{
  "providers": [
    {
      "name": "anthropic",
      "models": ["claude-sonnet-4-20250514"],
      "priority": 1,
      "daily_budget": 5.00
    },
    {
      "name": "google",
      "models": ["gemini-2.5-flash"],
      "priority": 2,
      "daily_budget": 0
    }
  ]
}
        

Pipeline Stages

The pipeline is defined in config/pipeline.json. Each stage specifies the agent, model, and any gate conditions.

{
  "stages": [
    { "name": "plan", "agent": "james", "model": "claude-sonnet" },
    { "name": "implement", "agent": "marcus", "model": "claude-sonnet" },
    { "name": "test", "agent": "nina", "model": "gemini-flash" },
    { "name": "review", "agent": "oliver", "model": "claude-sonnet" },
    { "name": "pr", "agent": "rachel", "model": "gemini-flash" }
  ]
}
        

Directives

Directives are standing instructions that all agents follow. They are stored in the knowledge base and applied to every task. Examples:

"Always use TypeScript strict mode"
"Database migrations must be backward-compatible"
"Never commit directly to the main branch"
"Use pytest fixtures instead of setUp/tearDown"

Add directives via the dashboard under Knowledge > Directives, or via the API at POST /api/knowledge/directives.

Environment Variables

Variable	Description	Required
`ANTHROPIC_API_KEY`	API key for Local models	Yes
`GOOGLE_API_KEY`	API key for Gemini models	Yes
`ELEVENLABS_API_KEY`	API key for HD voice engine	For voice
`GITHUB_TOKEN`	Personal access token for repo operations	Yes
`DISCORD_BOT_TOKEN`	Token for the Discord integration	Optional
`NEXUS_SECRET_KEY`	Secret key for session encryption	Yes
`STRIPE_SECRET_KEY`	Stripe key for billing	For billing

API Reference

Nexus exposes a comprehensive REST API for managing tasks, projects, agents, and more. All responses are JSON. Base URL is your Nexus instance root (e.g. https://your-instance.example.com).

Authentication

All API requests require authentication. Use either a session cookie (set by the login page) or a Bearer token in the Authorization header.

# Obtain a token
curl -X POST https://your-instance/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "you@example.com", "password": "your-password"}'

# Response: {"token": "eyJhbGciOi...", "expires_at": "2026-04-05T12:00:00Z"}

# Use the token in subsequent requests
curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://your-instance/api/tasks
        

CSRF protection is enabled on state-changing requests (POST, PUT, DELETE). Include the X-CSRF-Token header with the value from the csrf_token cookie.

Pagination

List endpoints support pagination via page and per_page query parameters. Responses include total count, page info, and Link headers for navigation.

# Page 2, 25 items per page
GET /api/tasks?page=2&per_page=25

# Response includes pagination metadata
{
  "tasks": [...],
  "total": 142,
  "page": 2,
  "per_page": 25,
  "pages": 6
}
        

Tasks

Method	Path	Description
`GET`	`/api/tasks`	List tasks. Filters: `status`, `project`, `q` (search)
`POST`	`/api/tasks`	Create a task. Body: `{"project", "description", "provider"}`
`GET`	`/api/tasks/{id}`	Get task detail (status, logs, files, plan)
`POST`	`/api/tasks/{id}/cancel`	Cancel a running task
`GET`	`/api/tasks/{id}/logs`	Stream task execution logs
`GET`	`/api/tasks/{id}/files`	List files changed by this task
`GET`	`/api/tasks/search`	Full-text search across tasks

curl -X POST https://your-instance/api/tasks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-app",
    "description": "Add input validation to the user registration endpoint",
    "provider": "local"
  }'

# Response
{
  "task_id": "task_20260404_abc123",
  "status": "queued",
  "project": "my-app",
  "created_at": "2026-04-04T12:00:00Z"
}
            

import requests

resp = requests.post(
    "https://your-instance/api/tasks",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "project": "my-app",
        "description": "Add input validation to registration",
        "provider": "local"
    }
)
task = resp.json()
print(f"Task {task['task_id']} is {task['status']}")
            

const resp = await fetch("https://your-instance/api/tasks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    project: "my-app",
    description: "Add input validation to registration",
    provider: "local"
  })
});
const task = await resp.json();
console.log(`Task ${task.task_id} is ${task.status}`);
            

Projects

Method	Path	Description
`GET`	`/api/projects`	List projects. Filters: `q` (search)
`POST`	`/api/projects`	Create a project. Body: `{"name", "repo_url?", "description?"}`
`GET`	`/api/projects/{name}/details`	Get project details including task count
`PUT`	`/api/projects/{name}/settings`	Update project settings

Agents & Staff

Method	Path	Description
`GET`	`/api/staff`	List all agents with profiles, providers, and status
`GET`	`/api/staff/{id}/profile`	Get detailed agent profile
`GET`	`/api/staff/{id}/memory`	Agent's memory and learned context
`GET`	`/api/activity/agents`	Real-time agent status (active, idle, thinking)
`GET`	`/api/activity`	Recent activity events. Param: `limit`

Governance

Method	Path	Description
`GET`	`/api/governance/proposals`	List pending proposals
`POST`	`/api/governance/proposals/{id}/approve`	Approve a proposal
`POST`	`/api/governance/proposals/{id}/reject`	Reject a proposal

Knowledge Base

Method	Path	Description
`GET`	`/api/knowledge/search`	Search knowledge. Param: `q`
`POST`	`/api/knowledge/directives`	Add a standing directive
`GET`	`/api/knowledge/directives`	List active directives

Usage & Billing

Method	Path	Description
`GET`	`/api/usage/summary`	Current usage vs plan limits
`GET`	`/api/billing/usage`	Billing-period usage breakdown
`GET`	`/api/cost/summary`	Current cost breakdown by provider

Data Export

Method	Path	Description
`GET`	`/api/export/tasks`	Download all tasks as JSON
`GET`	`/api/export/agents`	Download agent configurations as JSON
`GET`	`/api/export/all`	Download everything as a ZIP archive

Real-Time WebSockets

Nexus provides several WebSocket endpoints for live updates:

Endpoint	Description
`ws://host/ws/activity`	Global activity stream — all agent events in real-time
`ws://host/ws/workspace/{task_id}`	Task-specific workspace — file changes, plan progress, agent thoughts
`ws://host/ws/terminal/{task_id}`	Live terminal output for a running task
`ws://host/ws/pulse`	System heartbeat — task counts, agent status, health
`ws://host/ws/hive/{client_id}`	Agent collaboration messages — observe agent-to-agent communication

const ws = new WebSocket("wss://your-instance/ws/activity");

ws.onmessage = (event) => {
  const ev = JSON.parse(event.data);
  console.log(`[${ev.event_type}] ${ev.agent_name}: ${ev.content?.message || ''}`);
  // event_type: THINKING, CODING, TERMINAL, PLANNING, REVIEW, TEST, etc.
};
            

Rate limits: API requests are rate-limited per user session. Free tier: 60 req/min. Starter: 120 req/min. Pro/Enterprise: 300 req/min.

Webhooks

Webhooks let you receive real-time HTTP callbacks when events happen in Nexus. Use them to integrate with CI/CD, Slack, monitoring tools, or your own systems.

Registering a Webhook

Register a webhook via the API or the Settings page. Each webhook has a target URL, a secret for signature verification, and a list of event types to subscribe to.

curl -X POST https://your-instance/api/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/nexus-webhook",
    "secret": "your-webhook-secret",
    "events": ["task.completed", "task.failed", "agent.error"]
  }'
        

Use wildcard subscriptions to match groups of events: task.* matches all task events, and * matches everything.

Event Types

Event	Trigger
`task.created`	A new task is created
`task.completed`	A task finishes successfully
`task.failed`	A task fails (error, timeout, or rejection)
`task.timeout`	A task exceeds its time limit
`agent.started`	An agent begins working on a task
`agent.stopped`	An agent stops (completed or idle)
`agent.error`	An agent encounters an unrecoverable error
`agent.escalation`	An agent escalates to a human for approval
`billing.invoice.paid`	A billing invoice is successfully paid
`billing.invoice.failed`	A billing payment fails
`billing.subscription.changed`	Subscription plan changes (upgrade/downgrade)
`voice.call.started`	A voice call begins (agent to user or user to agent)
`voice.call.ended`	A voice call ends
`system.health.degraded`	System health drops below threshold
`system.health.restored`	System health returns to normal

Payload Format

Every webhook delivery is a POST request with a JSON body:

{
  "event": "task.completed",
  "timestamp": "2026-04-04T14:32:10Z",
  "delivery_id": "wh_abc123def456",
  "data": {
    "task_id": "task_20260404_abc123",
    "project": "my-app",
    "description": "Add input validation to registration",
    "status": "completed",
    "agent": "james",
    "duration_seconds": 127,
    "files_changed": 3
  }
}
        

Signature Verification

Each delivery includes an X-Nexus-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret. Always verify this signature to ensure the payload is authentic.

import hmac, hashlib

def verify_webhook(payload_bytes, signature, secret):
    expected = hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your Flask/FastAPI handler:
sig = request.headers.get("X-Nexus-Signature")
if not verify_webhook(request.data, sig, WEBHOOK_SECRET):
    return "Invalid signature", 401
            

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
      .update(body).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

// In your Express handler:
app.post('/nexus-webhook', (req, res) => {
  const sig = req.headers['x-nexus-signature'];
  if (!verifyWebhook(req.rawBody, sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Bad signature');
  }
  const event = req.body;
  console.log(`Received: ${event.event}`, event.data);
  res.sendStatus(200);
});
            

Delivery & Retries

Nexus expects your endpoint to return a 2xx status within 10 seconds. If delivery fails, Nexus retries with exponential backoff: 1 min, 5 min, 30 min, 2 hours (4 attempts total). Failed deliveries are logged in the webhook health dashboard.

Managing Webhooks

Method	Path	Description
`GET`	`/api/webhooks`	List registered webhooks
`POST`	`/api/webhooks`	Register a new webhook
`PUT`	`/api/webhooks/{id}`	Update a webhook (URL, events, active/paused)
`DELETE`	`/api/webhooks/{id}`	Delete a webhook
`GET`	`/api/webhooks/{id}/health`	Delivery success rate and recent failures

Use a webhook to trigger a GitHub Actions workflow when Nexus completes a task:

# 1. Create a repository dispatch webhook:
curl -X POST https://your-instance/api/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "url": "https://api.github.com/repos/you/repo/dispatches",
    "secret": "your-secret",
    "events": ["task.completed"],
    "headers": {
      "Authorization": "token YOUR_GITHUB_PAT",
      "Accept": "application/vnd.github.v3+json"
    }
  }'

# 2. In .github/workflows/nexus-deploy.yml:
on:
  repository_dispatch:
    types: [task.completed]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying changes from Nexus task"
            

Send a Slack message when an agent hits an error:

# Point webhook at a Slack incoming webhook URL
curl -X POST https://your-instance/api/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "events": ["agent.error", "task.failed"],
    "transform": "slack"
  }'

# Nexus formats the payload as a Slack Block Kit message
# with event details, agent name, and error description.
            

Testing webhooks: Use a service like webhook.site or smee.io to inspect webhook payloads during development.

Voice & Communication

Nexus supports multiple communication channels. Agents can reach you, and you can reach them, through any of these methods.

Voice Calls

Nexus runs a built-in telephony engine that handles voice calls. Each agent has their own extension and a unique natural AI voice. Audio understanding uses advanced speech AI for natural conversation flow.

To receive calls from your AI team:

Configure a SIP client (Ooma, Obi, Linphone, or any softphone)
Register with your Nexus SIP credentials (provided in the dashboard under Settings > Voice)
Agents will call you when they need approval, have status updates, or complete tasks

To call an agent, dial their extension number. The default extensions are listed in the dashboard.

Discord

Connect the Nexus Discord bot to your server. Agents post in designated channels and respond to direct messages. You can assign tasks, approve proposals, and check status directly from Discord.

Set DISCORD_BOT_TOKEN in your environment and invite the bot to your server. Channel mapping is configured in the dashboard.

Push Notifications

Nexus sends push notifications via ntfy.sh for critical alerts, proposal requests, and task completions. Subscribe to your notification topic in the dashboard under Settings > Notifications.

Email (Microsoft 365)

With a connected Microsoft 365 account, agents can send and read emails, create calendar events, and manage To Do lists. This requires the Microsoft Graph API integration configured in Settings > Integrations.

Frequently Asked Questions

Copilot and Cursor are code completion tools that assist you while you type. Nexus is an autonomous workforce. You delegate a task, and a team of specialised agents plans, implements, tests, reviews, and ships the code while you do something else. Nexus also handles project management, voice communication, and deployment -- it is a team, not a tool.

Nexus works with any language that the underlying LLMs support. This includes Python, JavaScript, TypeScript, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, and more. The agents adapt to whatever language and framework your project uses.

Yes. You provide a GitHub personal access token with repo scope during setup. This token is encrypted at rest and used only for repository operations. Agents clone, pull, and push through authenticated HTTPS.

Yes, portions of your code are sent to AI providers (Anthropic, Google, OpenAI) as part of task execution. We use their enterprise APIs with data retention policies that prevent your code from being used for model training. Enterprise plans offer dedicated infrastructure with additional isolation guarantees. You can also route sensitive tasks to local Ollama models that never leave your server.

On Professional plans, you can set directives that shape agent behaviour, adjust autonomy levels, and configure which models each agent uses. Enterprise plans allow fully custom agent roles, personas, voices, and brain twin cloning from your own communication patterns.

Nexus runs health checks after every deployment. If a health check fails, the system automatically rolls back to the previous working version and notifies you. The failed deployment is logged with full diagnostics so the agents can investigate and fix the issue in a subsequent task.

Nexus provides several cost control mechanisms: per-provider daily budgets, per-agent cost caps, automatic routing to free-tier models when possible, and real-time cost dashboards. You can set hard budget limits that prevent any API calls once reached, and configure alerts at custom thresholds.