Quickstart

Get up and running with the NeuroCLI API in under a minute.

1. Get an API Key

Navigate to the API Dashboard and generate a secret key. Do not share this key or expose it in client-side code like browsers or mobile apps.

2. Make your first request

You can use standard HTTP clients to interact with the API. Here is a basic cURL request to generate a chat completion:

curl https://neurocli.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEUROCLI_API_KEY" \
  -d '{
    "model": "neurocli medical gamma",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Terminal CLI v0.4.0+

NeuroCLI comes with a built-in command line interface for quick workflows directly from your terminal.

Ensure that you have set your API key as an environment variable before using the CLI:

# Windows
set NEUROCLI_API_KEY=your_api_key

# Mac/Linux
export NEUROCLI_API_KEY=your_api_key

Available Commands

The following commands are available out of the box:

1. Code Generation

Automatically generate a boilerplate application so you don't have to start from scratch.

neurocli init                 # Generates a Python script (neurocli_app.py)
python -m neurocli.cli init   # Failsafe alternative if neurocli is not in PATH
neurocli init --lang python   # Generates a Python script
neurocli init --lang node     # Generates a Node.js script (neurocli_app.js)

2. Check API Stats

Verify your configuration and test your active API connection.

neurocli stats

3. Interactive Chat

Launch an interactive, terminal-based chat session to test the neurocli medical gamma model natively without writing a script.

neurocli chat

python -m neurocli.cli stats

C:\Users\YourUsername\AppData\Roaming\Python\Python314\Scripts\neurocli stats

Models

NeuroCLI offers a range of models optimized for different tasks, speeds, and price points.

Clinical Reasoning Core

Process medical forms and analyze real-time patient data in seconds.

The NeuroCLI Medical API is powered by neurocli-medical-gamma, an LLM fine-tuned specifically on medical literature and clinical workflows. It guarantees rapid data ingestion for near-instant form processing and diagnostic reasoning.

Real-Time Form Processing

Send unstructured clinical notes or raw forms, and the reasoning core will extract key entities, suggest diagnostic pathways, and structure the data securely.

from neurocli import AsyncNeuroCLI
import asyncio

client = AsyncNeuroCLI(api_key="PASTE_API_KEY_HERE")

async def process_intake(notes: str):
    # Analyzes medical forms in seconds
    response = await client.medical.reasoning.create(
        model="neurocli-medical-gamma",
        data=notes,
        realtime_sync=True
    )
    print(response.extracted_entities)
    print(response.clinical_summary)

asyncio.run(process_intake("Patient presents with..."))

Node.js Example

import { NeuroCLI } from 'neurocli-sdk';

const client = new NeuroCLI({ 
  apiKey: 'PASTE_API_KEY_HERE' 
});

async function processIntake(notes: string) {
  console.log("Calling Medical API...");
  try {
    const response = await client.medical.reasoning.create({
      model: 'neurocli-medical-gamma',
      data: notes,
      realtime_sync: true
    });
    console.log("\n✅ Response received:");
    console.log(response.extracted_entities);
  } catch (err) {
    console.error("❌ Error:", err);
  }
}

processIntake('Patient presents with severe headache and nausea.');

Text Generation

The core Chat Completions API allows models to respond to conversational inputs.

Chat models take a list of messages as input and return a model-generated message as output. Each message has a role (system, user, or assistant) and content.

Roles Explained:

• System: Sets the behavior and personality of the assistant (e.g., "You are a helpful coding tutor").
• User: The prompt or instructions from the human user.
• Assistant: Prior responses from the model. Providing these gives the model "memory" of the conversation context.

Streaming

Receive responses in real-time as they are generated by the model.

By setting stream: true in your request payload, the API will return Server-Sent Events (SSE). This significantly improves the perceived latency for your end users.

from neurocli import NeuroCLI

client = NeuroCLI(api_key="PASTE_API_KEY_HERE")

response = client.chat.completions.create(
    model="neurocli-nano",
    messages=[{"role": "user", "content": "Write a poem."}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

Node.js Example

import { NeuroCLI } from 'neurocli-sdk';
const client = new NeuroCLI({ apiKey: 'PASTE_API_KEY_HERE' });

const stream = await client.chat.completions.create({
  model: 'neurocli-delta',
  messages: [{ role: 'user', content: 'Write a poem.' }],
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Prompt Engineering

Best practices for getting optimal results from NeuroCLI models.

LLMs are highly sensitive to how instructions are phrased. Follow these tips:

• Be specific: Avoid vague requests. Specify the format, tone, and length of the desired output.
• Provide examples (Few-Shot): Include a few examples of desired input/output pairs in the message history to show the model the pattern.
• Let the model think: Ask the model to explain its reasoning step-by-step before giving the final answer to improve accuracy on complex math or logic problems.

Function Calling

Connect NeuroCLI models to external tools and APIs.

You can describe functions to the model, and it will intelligently choose to output a JSON object containing arguments to call those functions. This allows you to fetch real-time data or perform actions.

Gamified RLHF Data Export

Leverage user interactions to continuously train your models.

The Gamified Reinforcement Learning from Human Feedback (RLHF) feature allows you to collect high-quality preference data directly from the chat UI.

• Upvote/Downvote System: Users can rate AI responses instantly. The system automatically associates the user's exact query with the generated response.
• Trainer Certification: Gamification mechanics track the number of valid interactions. When users reach 5,000 upvoted queries, they become eligible for a Letter of Recommendation (LOR) and an AI Model Trainer Certificate.
• JSONL Export: You can export this curated data using the export_training_data.py utility script to fine-tune new models automatically.

python export_training_data.py

This will generate a training_data.jsonl file ready to be used as a dataset for LLM fine-tuning pipelines.

Dashboard UI

Navigate the NeuroCLI API Dashboard efficiently.

The new NeuroCLI dashboard introduces premium developer features designed to make your workflow seamless.

• Command Palette: Press Ctrl + K anywhere on the dashboard to open the quick-search palette. You can instantly jump to webhooks, logs, or toggle settings.
• Theme Toggle: Switch between dark and light modes via the Sun/Moon icon in the sidebar or the Command Palette.
• Live Code Sandbox: Inside the Playground, you will find an interactive JS sandbox to write `fetch` requests and execute them live in your browser.
• Usage Analytics: The Request Logs section now includes a real-time Chart.js graph of your API call volume over time.

Advanced API Key Scopes

Organize and secure your access using highly granular permissions.

The NeuroCLI dashboard allows you to generate multiple API keys. Each key can be restricted to specific models or actions, helping you control costs and improve security. Available scopes include:

• Full Access: Can access all models and endpoints.
• neurocli-nano Only: Restricted to the fastest, cheapest model.
• neurocli medical gamma Only: Restricted to clinical and complex reasoning models.
• Read-Only Analytics: Can only read logs and usage stats, cannot make inference requests.

If a key with a restricted scope attempts to access an unauthorized model, the backend immediately rejects the request with a 403 Forbidden error.

Endpoints

• POST /api/generate_key: Creates a new scoped API key. Requires name and scope in the JSON payload.
• POST /api/delete_key: Revokes an existing API key immediately. Requires the key's id.

Example: Generate a Key

curl -X POST https://api.neurocli.com/api/generate_key \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{"name": "Production Key", "scope": "Full Access"}'

Webhooks & Usage Alerts

Receive real-time event notifications and quota alerts.

Webhooks: Allow your application to receive asynchronous HTTP POST payloads when specific events occur within your account, such as a background task completing.

Usage Alerts & Notifications: You can set an Alert Threshold (e.g., 80%) and a Notification Email. The NeuroCLI backend natively tracks your monthly usage, and triggers an alert when your volume crosses this threshold, ensuring you are never caught off guard by rate limits.

Smart Webhook Retries: On the Webhooks page, you can test your endpoints instantly by clicking the Test button next to any webhook. It will send a sample payload and visually confirm the HTTP response code (e.g., Sent (200)).

Endpoints

• POST /api/webhooks: Registers a new webhook. Requires target_url and event_type (e.g., all, billing.limit_reached).
• POST /api/webhooks/retry: Manually test an existing webhook. Requires webhook_id.
• POST /api/webhooks/delete: Deletes an existing webhook by id.

Example: Register a Webhook

curl -X POST https://api.neurocli.com/api/webhooks \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{"target_url": "https://myapp.com/webhook", "event_type": "all"}'

Prompt Registry

Version control your system prompts directly in the NeuroCLI Dashboard.

Instead of hardcoding massive system prompts directly inside your source code, NeuroCLI allows you to save and manage prompts remotely.

• Decoupled Logic: Update AI behavior instantly without requiring a code deployment.
• Version Control: Keep track of different prompt iterations.
• SDK Support: Simply pass prompt_id="pr_123" in the SDK and the backend will inject the prompt automatically.

Model A/B Testing

Route traffic between multiple models to evaluate performance.

NeuroCLI's A/B Testing routing allows you to split inference traffic between two models based on a defined percentage (e.g., 50% / 50%).

• Seamless Integration: Pass the test ID as the model parameter (e.g., model="abtest_123") and NeuroCLI handles the rest.
• Cost Optimization: Evaluate whether a smaller, cheaper model performs adequately for a subset of your users.

Shadow Distillation

Zero-touch model distillation for your highest volume prompts.

A completely unique feature only available in NeuroCLI. Shadow Distillation allows you to capture output from expensive, powerful models (like neurocli medical gamma) and automatically use that data to fine-tune and switch over to a cheaper model (like neurocli-nano).

• Automatic Interception: Create a rule specifying a target model, prompt prefix, and replacement model. NeuroCLI intercepts the traffic natively.
• Cost Savings: Reduce API costs by up to 99% for repetitive tasks without writing any infrastructure code.
• Seamless Fallback: The SDK and API usage remains exactly the same. The backend transparently routes and swaps models based on your active Shadow Distillation rules.

Team Collaboration (Organizations)

Share workspaces, API keys, and billing accounts with your team.

NeuroCLI now supports Organizations. You can invite team members to a shared workspace. All API Keys and Request Logs are tied to the organization (via org_id) rather than a single individual. This allows your team to collaborate seamlessly, manage shared keys, and view aggregate analytics.

Detailed Request Logs

Monitor your application's API usage and inspect payloads.

The NeuroCLI dashboard provides a comprehensive Request Debugger that displays your recent API calls, including the timestamp, endpoint hit, the model used, the HTTP status code, and precise latency measurements.

Payload Debugging: We log the exact JSON payload sent in every request. You can click the View Payload button next to any log entry to instantly inspect the raw JSON that was transmitted, making debugging incredibly easy.

Interactive API Playground

Test models instantly within your browser with streaming and history.

The Interactive API Playground allows you to select a model, adjust temperature, and set a system prompt without writing any code.

• Streaming Response (SSE): By toggling "Stream Response", the playground uses Server-Sent Events to stream the model's output piece-by-piece in real-time, matching the behavior of top-tier chat applications.
• Playground History: You can click "Save Prompt" to locally save your current configuration (model, system prompt, user query) to your browser's local storage. The History sidebar allows you to instantly load and retry your past prompts with a single click.

Proof-of-Deletion

Cryptographically prove that your data is wiped instantly.

For healthcare, finance, and defense sectors, data sovereignty is paramount. NeuroCLI offers an industry-first feature: self_destruct. When you pass this parameter, we guarantee that your payload bypasses all database logging, and the RAM space is securely zeroed out immediately after the response is sent.

{
  "model": "neurocli-delta",
  "messages": [{"role": "user", "content": "Analyze patient record."}],
  "self_destruct": true
}

Verification: Upon completion, the API returns an X-Proof-Of-Deletion header containing a SHA-256 hash. This hash is permanently written to our immutable public ledger, allowing your compliance teams to audit and verify that no PII was retained.

Self-Healing Output

Never write another parser or retry loop again.

LLMs occasionally fail to output the exact structure required (e.g., JSON schemas or specific regex patterns). With NeuroCLI, you can offload validation directly to our backend by passing a validation object in your payload.

{
  "model": "neurocli-delta",
  "messages": [{"role": "user", "content": "Generate a user ID."}],
  "validation": {
    "type": "regex",
    "pattern": "^USER_\\d{5}$",
    "max_retries": 3
  }
}

If the AI's output fails the regex, the server intercepts the response, appends an error message to the prompt, and automatically retries on your behalf until it succeeds or hits the retry limit.

BYOH Hybrid Router

Bring Your Own Hardware for ultimate data security.

The NeuroCLI Python SDK includes a built-in Hybrid Router. By setting hybrid_routing=True, the SDK activates a local PIIScanner before transmitting your payload.

If highly sensitive Personally Identifiable Information (like SSNs or Credit Card numbers) is detected in your prompt, the SDK transparently blocks the outbound request and re-routes it to your configured fallback (which defaults to the https://neurocli.in/api/isolated Enterprise Isolated Cluster).

from neurocli import NeuroCLI

client = NeuroCLI(api_key="your_key")

response = client.chat.completions.create(
    model="neurocli-delta",
    messages=[{"role": "user", "content": "My SSN is 123-45-6789. Can you process my loan?"}],
    hybrid_routing=True
)
# Automatically routed to the secure isolated cluster because PII was detected!

Multi-Agent Consensus (Swarm API)

Eliminate AI hallucinations by orchestrating a debate between three specialized agents behind a single API endpoint.

The Swarm API ensures extreme accuracy and safety by utilizing an internal peer-review process:

• Model A (The Expert): Generates the best possible initial answer.
• Model B (The Critic): Actively attempts to find flaws, safety risks, or hallucinations in the expert's answer.
• Model C (The Judge): Reviews the initial answer and the critique, resolves conflicts, and formulates the perfectly safe, final payload.

Endpoint

Example Request (cURL)

curl -X POST https://neurocli.in/v1/swarm/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "neurocli-swarm-engine",
    "messages": [
      {
        "role": "user",
        "content": "Is it safe to mix Lisinopril and Spironolactone?"
      }
    ]
  }'

Example Request (Python SDK)

from neurocli import NeuroCLI

client = NeuroCLI(api_key="YOUR_API_KEY")

response = client.swarm.chat(
    model="neurocli-swarm-engine",
    messages=[
        {"role": "user", "content": "Is it safe to mix Lisinopril and Spironolactone?"}
    ]
)

# The final verified answer
print(response.choices[0].message.content)

# View the internal multi-agent debate
for entry in response.transcript:
    print(f"{entry['agent']}: {entry['content']}")

Example Response

The response includes the final optimized answer in the standard choices array, alongside a transcript array documenting the internal multi-agent debate.

{
  "id": "swarm-123",
  "object": "chat.completion",
  "created": 1718544000,
  "model": "neurocli-swarm-engine",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Co-administration significantly increases the risk of severe hyperkalemia. Close monitoring is required."
      },
      "finish_reason": "stop"
    }
  ],
  "transcript": [
    {
      "agent": "Model A (Expert)",
      "content": "Lisinopril and Spironolactone can be mixed but may cause hyperkalemia."
    },
    {
      "agent": "Model B (Critic)",
      "content": "The initial answer downplays the severity. It must explicitly highlight the risk of severe hyperkalemia and recommend monitoring."
    },
    {
      "agent": "Model C (Judge)",
      "content": "Co-administration significantly increases the risk of severe hyperkalemia. Close monitoring is required."
    }
  ]
}