API Reference

Neura API Documentation

Everything you need to integrate with the Neura platform. Build autonomous agents, manage conversations, and deploy AI-powered workflows.

Base URLhttps://api.neura.ai

ProtocolREST + SSE + GraphQL

FormatJSON

Introduction

The Neura API gives you programmatic access to autonomous AI agents, knowledge bases, model inference, and workflow automation. All endpoints return JSON and use standard HTTP status codes.

Base URL

text

https://api.neura.ai

Key Concepts

Agents

Autonomous AI entities with custom prompts, tools, and knowledge.

Conversations

Persistent chat threads tied to an agent.

Jobs

Tracked tasks that agents execute asynchronously.

Knowledge Bases

Vector-indexed document stores for RAG.

Instructions

Standing rules, scheduled tasks, and conditional behaviors.

Tools

AI capabilities (image gen, TTS) and agent-as-tool integrations.

Request Format

All request bodies must be JSON with Content-Type: application/json. All resource IDs are UUIDs. Timestamps are ISO 8601 format.

Authentication

Neura supports two authentication methods: JWT Bearer tokens for platform users, and API Keys for external integrations.

JWT Bearer Tokens

Obtain a token by calling the GraphQL login mutation. Include it in the Authorization header.

curl -X POST https://api.neura.ai/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { login(email: \\"user@example.com\\", password: \\"secret\\") { accessToken refreshToken user { id email } } }"}'

Then use the token in subsequent requests:

HTTP Header

Authorization: Bearer <your_access_token>

API Keys

For external integrations, create an API key for your agent. API keys authenticate via the X-API-Key header and are scoped to a single agent.

HTTP Header

X-API-Key: <your_api_key>

Quick Start

Get up and running in 3 steps.

Create an Agent

curl -X POST https://api.neura.ai/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "description": "A helpful research agent",
    "model_id": "deepseek-ai/DeepSeek-V3.2"
  }'

Create an API Key

curl -X POST https://api.neura.ai/api/agents/{agent_id}/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_name": "production", "rate_limit": 60}'

# Response: {"key": "nk-abc123...", "key_id": "..."}
# Save the key! It is only shown once.

Chat with Your Agent

curl -X POST https://api.neura.ai/api/v1/agents/{agent_id}/chat \
  -H "X-API-Key: nk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the latest trends in AI agent frameworks"}'

# Response:
# {
#   "answer": "Here are the key trends...",
#   "sources": ["https://..."],
#   "usage": {"total_cost": 0.003, "latency_ms": 1200}
# }

Agents

Create, configure, and manage autonomous AI agents.

GET/api/agents— List all your agents

POST/api/agents— Create a new agent

GET/api/agents/{agent_id}— Get agent details

PUT/api/agents/{agent_id}— Update an agent

DELETE/api/agents/{agent_id}— Delete an agent

Create Agent Parameters

Parameter	Type	Required	Description
name	string	Required	Display name for the agent
description	string	Optional	What the agent does
model_id	string	Optional	LLM model ID. Default: deepseek-ai/DeepSeek-V3.2. List via GET /api/agent/models
system_prompt	string	Optional	Custom system prompt / instructions
kb_ids	string[]	Optional	Knowledge base IDs to attach
use_web_search	boolean	Optional	Enable web search. Default: true
max_iterations	integer	Optional	Max reasoning iterations. Default: 10
search_depth	integer	Optional	5 (quick), 15 (balanced), 30 (thorough)
visibility	string	Optional	"private" or "public" (marketplace)
category	string	Optional	Agent category for marketplace
tags	string[]	Optional	Searchable tags
tool_description	string	Optional	Description when this agent is used as a tool by other agents
settings	object	Optional	Additional agent settings
pricing	object	Optional	Pricing config for marketplace agents

Example: Create Agent

curl -X POST https://api.neura.ai/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "description": "Deep web research with citations",
    "model_id": "deepseek-ai/DeepSeek-V3.2",
    "use_web_search": true,
    "max_iterations": 15,
    "search_depth": 30,
    "system_prompt": "You are a thorough researcher. Always cite sources."
  }'

Response

JSON

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Research Agent",
  "description": "Deep web research with citations",
  "model_id": "deepseek-ai/DeepSeek-V3.2",
  "use_web_search": true,
  "max_iterations": 15,
  "created_at": "2025-01-15T10:30:00Z"
}

Agent Tools

Configure inference tools (image generation, TTS, video) and agent-as-tool capabilities.

GET/api/tools/inference?sync=false— List available inference tools. Pass sync=true to refresh from providers

POST/api/tools/sync— Sync latest tools from providers

GET/api/tools/agents— List agents available as tools

PUT/api/agents/{agent_id}/tools— Configure an agent's tool permissions

GET/api/agents/{agent_id}/tools— Get agent's current tool configuration

Tool Categories

Tools are grouped by model family. Categories include LLMs, image generators, and more.

DeepSeek

Reasoning and general-purpose LLMs

Llama

Meta's open-weight models

Qwen

Alibaba's multilingual models

FLUX / Stability

Image generation models

Configure Agent Tools

Parameter	Type	Required	Description
enable_agent_tools	boolean	Optional	Allow this agent to call other agents as tools
enable_inference_tools	boolean	Optional	Allow access to AI generation tools (images, audio, video)
auto_select_tools	boolean	Optional	Let the agent automatically select appropriate tools
selected_agent_ids	string[]	Optional	Specific agent IDs to enable as tools
selected_inference_tools	string[]	Optional	Specific inference tool names to enable

Example: Enable Tools

curl -X PUT https://api.neura.ai/api/agents/{agent_id}/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_inference_tools": true,
    "enable_agent_tools": true,
    "auto_select_tools": true
  }'

Inference Tools Response

JSON

{
  "categories": {
    "flux": [
      {
        "tool_id": "uuid-1234",
        "name": "black-forest-labs/FLUX.1-schnell",
        "display_name": "FLUX.1 Schnell",
        "description": "Fast high-quality image generation",
        "provider": "black-forest-labs",
        "model_id": "black-forest-labs/FLUX.1-schnell",
        "cost_per_call": 0.003,
        "output_price": 0.006,
        "cost_unit": "per_call",
        "max_duration_seconds": 300,
        "logo_url": "https://..."
      }
    ],
    "deepseek": [ // ... ],
    "llama": [ // ... ]
  },
  "total": 45
}

Chat & Streaming

Send messages to agents and receive responses via REST or real-time streaming.

POST/api/agents/{agent_id}/chat— Non-streaming chat (JWT auth)

POST/api/agents/{agent_id}/chat/stream— Streaming chat via SSE (JWT auth)

ⓘ

These endpoints use JWT Bearer token auth and are for platform users. For external integrations with API key auth, see the section.

Request Parameters

Parameter	Type	Required	Description
query	string	Required	The user message / prompt
model_id	string	Optional	Override the agent's default model. Default: deepseek-ai/DeepSeek-V3.2
kb_ids	string[]	Optional	Knowledge bases to search
conversation_history	object[]	Optional	Previous messages [{role, content}]
use_web_search	boolean	Optional	Enable web search. Default: true
max_iterations	integer	Optional	Max reasoning loops. Default: 10
search_depth	integer	Optional	5 (quick) / 15 (balanced) / 30 (thorough)
enable_inference_tools	boolean	Optional	Enable image/audio/video generation tools. Default: false
selected_inference_tools	string[]	Optional	Specific inference tool names to enable
enable_agent_tools	boolean	Optional	Enable calling other agents as tools. Default: false
selected_agent_ids	string[]	Optional	Specific agent IDs to enable as tools
auto_select_tools	boolean	Optional	Let the agent auto-select appropriate tools. Default: false
session_context	string	Optional	Temporary document context for this request
detailed_mode	boolean	Optional	Return additional agent metadata in response. Default: false

Non-Streaming Example

curl -X POST https://api.neura.ai/api/agents/{agent_id}/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key differences between RAG and fine-tuning?",
    "use_web_search": true,
    "search_depth": 15
  }'

Response

JSON

{
  "answer": "RAG (Retrieval-Augmented Generation) and fine-tuning serve different purposes...",
  "sources": ["https://arxiv.org/...", "https://docs.example.com/..."],
  "tool_calls": [{"tool": "web_search", "args": {"query": "RAG vs fine-tuning"}}],
  "iterations": 3,
  "costs": {
    "embedding_cost": 0.0001,
    "llm_cost": 0.0024,
    "search_cost": 0.001,
    "sandbox_cost": 0.0,
    "total_cost": 0.0035
  },
  // Additional fields for saved-agent chat:
  "agent_id": "a1b2c3d4-...",
  "agent_name": "Research Agent",
  "memories_used": 3,
  "instructions_active": 2,
  "context_loaded": true
}

Streaming (SSE) Example

ⓘ

The streaming endpoint returns Server-Sent Events. Each event is a JSON object prefixed with data: . See the section for all event types.

curl -N -X POST https://api.neura.ai/api/agents/{agent_id}/chat/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain quantum computing"}'

# Output (SSE stream):
# data: {"type":"status","message":"Agent loaded"}
# data: {"type":"token","content":"Quantum"}
# data: {"type":"token","content":" computing"}
# data: {"type":"done","answer":"Quantum computing...","costs":{...}}

Conversations

Manage persistent chat threads for your agents.

GET/api/agents/{agent_id}/conversations— List conversations (lightweight)

GET/api/agents/{agent_id}/conversations/{conversation_id}— Get full conversation with messages

POST/api/agents/{agent_id}/conversations— Create a conversation

PUT/api/agents/{agent_id}/conversations/{conversation_id}— Update conversation

DELETE/api/agents/{agent_id}/conversations/{conversation_id}— Delete conversation

Create Conversation

Parameter	Type	Required	Description
title	string	Required	Conversation title
messages	object[]	Required	Array of {role, content} messages
sandboxState	object	Optional	Sandbox session state (terminal, files, artifacts)

List Response

JSON

{
  "conversations": [
    {
      "id": "conv-uuid-1234",
      "title": "Research on AI trends",
      "messageCount": 12,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T11:45:00Z",
      "agentId": "agent-uuid-5678"
    }
  ]
}

Jobs & Tasks

Track and manage agent tasks with progress, sub-jobs, and lifecycle management.

GET/api/agents/{agent_id}/jobs— List jobs

POST/api/agents/{agent_id}/jobs— Create a job

GET/api/agents/{agent_id}/jobs/{job_id}— Get job details

PUT/api/agents/{agent_id}/jobs/{job_id}— Update job progress

DELETE/api/agents/{agent_id}/jobs/{job_id}— Delete job

GET/api/agents/{agent_id}/jobs/{job_id}/tree— Get job tree (parent + children)

GET/api/agents/{agent_id}/jobs/by-resource/{resource_id}— Get job by resource ID

POST/api/agents/{agent_id}/jobs/close-stale— Auto-close stale in_progress jobs

Create Job Parameters

Parameter	Type	Required	Description
name	string	Required	Job name
job_type	string	Optional	general, campaign, inference, research, automation, batch, pipeline
description	string	Optional	Detailed description
parent_job_id	string	Optional	Parent job UUID for sub-tasks
priority	integer	Optional	1-10, default: 5
total_steps	integer	Optional	Expected steps, default: 1
input_data	object	Optional	Input parameters for the job
bucket_id	string	Optional	Memory bucket UUID to associate
assigned_model	string	Optional	Model ID for this job
assigned_provider	string	Optional	Provider for this job
tags	string[]	Optional	Searchable tags

Job Statuses

pendingin_progresscompletedfailedpausedcancelled

List Jobs (with Filters)

Parameter	Type	Required	Description
status	string	Optional	Filter by status
job_type	string	Optional	Filter by type
parent_only	boolean	Optional	Only top-level jobs
limit	integer	Optional	Max results (default: 50)
offset	integer	Optional	Pagination offset

Dataset Creation Lab

Generate high-quality, validated Q&A datasets from any topic using a multi-agent pipeline: Analyzer → Researcher → Analyst → FactExtractor → Teacher → Critic → Export.

POST/api/datasets/pipeline/start— Start dataset creation pipeline

GET/api/datasets/pipeline/{job_id}/status— Get pipeline status

GET/api/datasets— List your datasets

Start Pipeline Parameters

Parameter	Type	Required	Description
topic	string	Required	The subject matter for dataset generation
job_name	string	Optional	Human-readable job name (defaults to "Dataset: {topic}")
target_samples	integer	Optional	Number of Q&A pairs to generate (default: 50)
data_source_mode	string	Optional	hybrid \| web_only \| scholarly_only \| hypothesis \| hypothesis_grounded \| user_docs_only
model_id	string	Optional	Base model for generation (default: deepseek-ai/DeepSeek-V3.2)
teacher_models	string[]	Optional	Specific teacher models to use
teacher_strategy	string	Optional	all_models \| round_robin \| parallel
pairs_per_source	integer	Optional	Q&A pairs per source document (default: 3)

Data Source Modes

hybridweb_onlyscholarly_onlyhypothesishypothesis_groundeduser_docs_only

Teacher Strategies

all_modelsround_robinparallel

Pipeline Stages

analyzingresearchinganalysisfact_extractionteachingcriticismexportingcompleted

curl -X POST https://api.neura.ai/api/datasets/pipeline/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Kubernetes pod scheduling and resource management",
    "target_samples": 100,
    "data_source_mode": "hybrid",
    "teacher_strategy": "all_models",
    "pairs_per_source": 5
  }'

Pipeline Status Response

json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_name": "Dataset: Kubernetes pod scheduling",
  "status": "completed",
  "progress_percentage": 100,
  "current_stage": "completed",
  "actual_cost": 0.35,
  "created_at": "2026-02-23T10:30:00",
  "completed_at": "2026-02-23T10:45:00",
  "dataset": {
    "dataset_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "dataset_name": "Kubernetes pod scheduling - Dataset",
    "sample_count": 100,
    "total_tokens": 45000
  }
}

Knowledge Bases

Upload documents and create vector-indexed knowledge bases for RAG retrieval.

GET/api/agent/knowledge-bases— List your knowledge bases

POST/api/kb/upload— Upload document (multipart)

POST/api/datasets/{dataset_id}/enable-rag— Enable RAG indexing

GET/api/datasets/{dataset_id}/rag-status— Check RAG indexing status

Upload Document

ⓘ

File upload uses multipart/form-data instead of JSON. Supported formats: PDF, DOCX, TXT, MD, HTML.

curl -X POST https://api.neura.ai/api/kb/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "kb_id=kb-uuid-1234" \
  -F "file=@./document.pdf"

Instructions

Define standing rules, scheduled tasks, and conditional behaviors for your agents.

POST/api/agents/{agent_id}/instructions— Add an instruction

GET/api/agents/{agent_id}/instructions— List instructions

DELETE/api/agents/{agent_id}/instructions/{task_id}— Remove an instruction

Instruction Types

Standing

Always-active rules the agent follows (e.g., "Always respond in Spanish")

Scheduled

Recurring tasks with cron expressions (e.g., "Send daily report at 9am")

Conditional

Triggered by events (e.g., "Alert me when error rate exceeds 5%")

Add Instruction Parameters

Parameter	Type	Required	Description
instruction_type	string	Required	"standing", "scheduled", or "conditional"
action	string	Required	What the agent should do
trigger	string	Optional	For conditional: when to activate
schedule	string	Optional	For scheduled: cron expression (e.g., "0 9 * * *")
frequency	string	Optional	Human-readable: "hourly", "daily", "weekly"

Example: Add Standing Instruction

curl -X POST https://api.neura.ai/api/agents/{agent_id}/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction_type": "standing",
    "action": "Always include citations with URLs when referencing data"
  }'

List Response

JSON

{
  "agent_id": "a1b2c3d4-...",
  "agent_name": "Research Agent",
  "instructions": [
    {
      "task_id": "uuid-1234",
      "type": "standing",
      "action": "Always include citations with URLs",
      "trigger": null,
      "schedule": null,
      "frequency": null,
      "is_active": true,
      "execution_count": 47,
      "last_executed": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 1
}

Models

List available LLM models across all tiers.

GET/api/agent/models— List all available models

Model Providers

DeepInfra

Primary provider with wide model selection. DeepSeek, Llama, Qwen, Gemma, and more.

Atlas Cloud

Alternative provider with competitive pricing and low-latency inference.

Fine-tuned

Your custom trained models deployed from the Training page.

ⓘ

Use the model_id from this endpoint when creating or updating agents.

Response

JSON

{
  "models": [
    {
      "id": "deepseek-ai/DeepSeek-V3.2",
      "name": "DeepSeek V3.2",
      "provider": "deepseek-ai",
      "category": "deepseek",
      "context_length": 128000,
      "description": "Context: 128,000 tokens"
    },
    {
      "id": "meta-llama/Llama-3.3-70B-Instruct",
      "name": "Llama 3.3 70B Instruct",
      "provider": "meta-llama",
      "category": "llama",
      "context_length": 128000,
      "description": "Context: 128,000 tokens"
    }
  ],
  "default": "deepseek-ai/DeepSeek-V3.2"
}

Fine-Tuned Models

Access your custom trained models deployed on the Neura platform.

GET/api/agent/deployed-models— List your deployed fine-tuned models

GET/api/v1/models— List deployed models (OpenAI-compatible format)

Deployed Models Response

JSON

{
  "deployed_models": [
    {
      "model_id": "ft-abc123-my-model",
      "training_job_id": "tj-uuid-5678",
      "base_model": "meta-llama/Llama-3.3-70B-Instruct",
      "provider": "deepinfra",
      "dataset_name": "customer-support-qa",
      "completed_at": "2025-01-14T16:00:00Z"
    }
  ],
  "total": 1
}

Using Fine-Tuned Models

ⓘ

Fine-tuned models can be assigned to agents via the model_id field or used directly with the OpenAI-compatible endpoint.

# Use with an agent
curl -X PUT https://api.neura.ai/api/agents/{agent_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model_id": "ft-abc123-my-model"}'

OpenAI Compatible

Drop-in replacement for OpenAI API. Use your existing SDKs and tools.

POST/api/v1/chat/completions— Chat completions (OpenAI format)

GET/api/v1/models— List models (OpenAI format)

Request Parameters

Parameter	Type	Required	Description
model	string	Required	Model ID from /api/agent/models or deployed model ID
messages	object[]	Required	OpenAI message format [{role, content}]
max_tokens	integer	Optional	Max tokens. Default: 512
temperature	float	Optional	Sampling temperature. Default: 0.7
top_p	float	Optional	Nucleus sampling. Default: 0.9

Use with OpenAI SDK

curl -X POST https://api.neura.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V3.2",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

External Agent API

Let third parties interact with your agents via API keys.

POST/api/v1/agents/{agent_id}/chat— Chat with agent (API key auth)

POST/api/agents/{agent_id}/api-keys— Create API key

GET/api/agents/{agent_id}/api-keys— List API keys

DELETE/api/agents/{agent_id}/api-keys/{key_id}— Revoke API key

Chat Request

Parameter	Type	Required	Description
message	string	Required	The user message (alias: query)
query	string	Optional	Alternative to message — either field works
conversation_history	object[]	Optional	Previous messages [{role, content}] for context

Response

JSON

{
  "answer": "Based on the latest data, here are the key findings...",
  "sources": ["https://example.com/article1", "https://example.com/article2"],
  "usage": {
    "total_cost": 0.0035,
    "latency_ms": 1842
  }
}

Create API Key

Parameter	Type	Required	Description
key_name	string	Optional	Label for the key. Default: "Default"
rate_limit	integer	Optional	Requests per minute. Default: 60

Create Key Response

JSON

{
  "key_id": "uuid-5678",
  "key": "nk-abc123...",   // Only shown once!
  "key_name": "production",
  "rate_limit": 60,
  "endpoint": "https://api.neura.ai/api/v1/agents/{agent_id}/chat",
  "message": "API key created. Store it securely."
}

List Keys Response

JSON

{
  "keys": [
    {
      "key_id": "uuid-5678",
      "key_name": "production",
      "key_prefix": "nk-abc...",   // Never the full key
      "rate_limit": 60,
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "last_used": "2025-01-15T14:00:00Z"
    }
  ],
  "total": 1
}

ⓘ

The raw API key is only returned once at creation time. Store it securely. Subsequent list calls only show the key prefix.

Sandbox Sessions

Manage code execution sandbox state associated with agent conversations.

POST/api/agents/{agent_id}/sandbox-session— Save sandbox session state

GET/api/agents/{agent_id}/sandbox-session/{conversation_id}— Get sandbox session

DELETE/api/agents/{agent_id}/sandbox-session/{conversation_id}— Delete sandbox session

Save Session Parameters

Parameter	Type	Required	Description
conversation_id	string	Required	Conversation this sandbox belongs to
terminal_lines	object[]	Optional	Terminal output history
files	object[]	Optional	Files created in the sandbox
artifacts	object[]	Optional	Generated artifacts (HTML, images, etc.)
session	object	Optional	Session metadata (status, template, totalCost, runtimeMinutes)

Get Session Response

JSON

{
  "success": true,
  "session": {
    "session_id": "uuid-5678",
    "terminal_lines": [
      {"type": "command", "text": "python analyze.py"},
      {"type": "output", "text": "Processing 1000 records..."}
    ],
    "files": [
      {"name": "output.csv", "path": "/home/user/output.csv"}
    ],
    "artifacts": [
      {"type": "html", "title": "Dashboard", "content": "..."}
    ],
    "status": "running",
    "template": "python",
    "total_cost": 0.012,
    "runtime_minutes": 3.4,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z"
  }
}

API Usage Statistics

Monitor API consumption, costs, and performance metrics for your agents.

GET/api/agents/{agent_id}/api-usage— Get usage statistics

Query Parameters

Parameter	Type	Required	Description
period	string	Optional	"24h", "7d", or "30d". Default: "30d"

Response

JSON

{
  "period": "30d",
  "summary": {
    "total_requests": 1247,
    "total_tokens": 3842000,
    "total_cost": 4.82,
    "avg_latency_ms": 1340,
    "success_rate": 99.2,
    "error_count": 10,
    "last_request": "2025-01-15T14:30:00Z"
  },
  "daily": [
    {"date": "2025-01-15", "requests": 42, "cost": 0.18}
  ],
  "per_key": [
    {"key_id": "key-uuid", "key_name": "production", "requests": 800, "cost": 3.20}
  ]
}

SSE Stream Events

Event types emitted by streaming endpoints. Each line is prefixed with data: .

Event Type	Fields	Description
status	message: string	Connection and progress status updates
token	content: string	Streamed response token (append to output)
thinking	content: string	Agent reasoning / chain-of-thought
tool_call	tool: string, args: object	Tool invocation by the agent
tool_result	tool: string, result: object	Tool execution result
sources	sources: array	Retrieved references and citations
artifact	type: string, content: string	Generated artifact (HTML, image, etc.)
error	error: string	Error message
done	answer: string, costs: CostObject	Final response with cost breakdown

Cost Object

JSON

{
  "embedding_cost": 0.0001,    // Vector search embeddings
  "llm_cost": 0.0024,          // LLM inference
  "search_cost": 0.001,         // Web search (Tavily)
  "sandbox_cost": 0.005,        // Code execution sandbox
  "sub_agent_cost": 0.0,        // Calling other agents
  "inference_cost": 0.0,        // Image/audio generation
  "total_cost": 0.0085          // Sum of all costs
}

Error Handling

All errors follow a consistent format with appropriate HTTP status codes.

Error Response Format

JSON

{
  "error": "Human-readable error message",
  "detail": "Optional additional context"
}

Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Missing or invalid request parameters
401	Unauthorized	Missing or invalid authentication token
402	Payment Required	Insufficient credits balance
403	Forbidden	API key does not have access to this resource
404	Not Found	The requested resource does not exist
429	Too Many Requests	Rate limit exceeded for this API key
500	Internal Error	Unexpected server failure

Error Handling Example

# A 402 response when credits are exhausted:
curl -X POST https://api.neura.ai/api/agents/{agent_id}/chat \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "hello"}'

# HTTP/1.1 402 Payment Required
# {"error": "Insufficient credits", "detail": "Balance: $0.00"}

Rate Limits

API keys have configurable per-minute rate limits to protect your agents.

Default Limit

60 req/min

Configurable

Per Key

Error Code

429

Rate limits are set per API key at creation time via the rate_limit parameter. When exceeded, the API returns a 429 Too Many Requests response.

JSON

// 429 response when rate limited
{
  "error": "Rate limit exceeded: 61/60 per minute"
}

ⓘ

Platform API endpoints (JWT auth) have higher limits than external API key endpoints. Contact support for custom rate limits on high-volume integrations.

Neura Runtime

Run AI models locally on your device. Free, private, and offline-capable.

Installation

Two options — desktop app or CLI.

Desktop App (recommended for non-technical users)

Download from /download — one-click install with system tray, auto-connects to your browser.

CLI (developers)

bash

pip install neura-runtime
neura-runtime start

CLI Commands

bash

# Start the runtime daemon
neura-runtime start

# Check status
neura-runtime status

# Pair with your Neura account (6-digit code flow)
neura-runtime pair

# List detected local models (Ollama + LM Studio)
neura-runtime models

# List running Streamlit apps
neura-runtime apps

# Stop the daemon
neura-runtime stop

How It Works

Auto-detection: The Neura frontend polls localhost:9700/health every 5 seconds. When detected, your local models appear in the model selector.

Model discovery: Runtime queries Ollama (localhost:11434) and LM Studio (localhost:1234) for available models.

Inference: When you select a local model, chat completions are routed to your device via WebSocket tunnel. $0 cost.

Code execution: Python code runs in isolated Docker containers on your machine with strict sandboxing.

REST API (localhost:9700)

bash

# Health check
curl http://localhost:9700/health

# Full status (models, Docker, Streamlit apps)
curl http://localhost:9700/status

# Example response
{
  "version": "0.1.0",
  "docker_available": true,
  "local_models": [
    {
      "id": "local:ollama:llama3.2:latest",
      "name": "llama3.2:latest",
      "provider": "ollama",
      "parameter_size": "3B",
      "quantization": "q4_0"
    }
  ],
  "streamlit_apps": []
}

ⓘ

Local models work on all tiers, including free. Free tier users must use local runtime for all execution — no cloud fallback. Manage your runtime setup at /runtime in the dashboard.

Introduction

The Neura API gives you programmatic access to autonomous AI agents, knowledge bases, model inference, and workflow automation. All endpoints return JSON and use standard HTTP status codes.

Base URL

text

https://api.neura.ai

Key Concepts

Agents

Autonomous AI entities with custom prompts, tools, and knowledge.

Conversations

Persistent chat threads tied to an agent.

Jobs

Tracked tasks that agents execute asynchronously.

Knowledge Bases

Vector-indexed document stores for RAG.

Instructions

Standing rules, scheduled tasks, and conditional behaviors.

Tools

AI capabilities (image gen, TTS) and agent-as-tool integrations.

Request Format

All request bodies must be JSON with Content-Type: application/json. All resource IDs are UUIDs. Timestamps are ISO 8601 format.

Authentication

Neura supports two authentication methods: JWT Bearer tokens for platform users, and API Keys for external integrations.

JWT Bearer Tokens

Obtain a token by calling the GraphQL login mutation. Include it in the Authorization header.

curl -X POST https://api.neura.ai/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { login(email: \\"user@example.com\\", password: \\"secret\\") { accessToken refreshToken user { id email } } }"}'

Then use the token in subsequent requests:

HTTP Header

Authorization: Bearer <your_access_token>

API Keys

For external integrations, create an API key for your agent. API keys authenticate via the X-API-Key header and are scoped to a single agent.

HTTP Header

X-API-Key: <your_api_key>

Quick Start

Get up and running in 3 steps.

Create an Agent

curl -X POST https://api.neura.ai/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "description": "A helpful research agent",
    "model_id": "deepseek-ai/DeepSeek-V3.2"
  }'

Create an API Key

curl -X POST https://api.neura.ai/api/agents/{agent_id}/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key_name": "production", "rate_limit": 60}'

# Response: {"key": "nk-abc123...", "key_id": "..."}
# Save the key! It is only shown once.

Chat with Your Agent

curl -X POST https://api.neura.ai/api/v1/agents/{agent_id}/chat \
  -H "X-API-Key: nk-abc123..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize the latest trends in AI agent frameworks"}'

# Response:
# {
#   "answer": "Here are the key trends...",
#   "sources": ["https://..."],
#   "usage": {"total_cost": 0.003, "latency_ms": 1200}
# }

Agents

Create, configure, and manage autonomous AI agents.

GET/api/agents— List all your agents

POST/api/agents— Create a new agent

GET/api/agents/{agent_id}— Get agent details

PUT/api/agents/{agent_id}— Update an agent

DELETE/api/agents/{agent_id}— Delete an agent

Create Agent Parameters

Parameter	Type	Required	Description
name	string	Required	Display name for the agent
description	string	Optional	What the agent does
model_id	string	Optional	LLM model ID. Default: deepseek-ai/DeepSeek-V3.2. List via GET /api/agent/models
system_prompt	string	Optional	Custom system prompt / instructions
kb_ids	string[]	Optional	Knowledge base IDs to attach
use_web_search	boolean	Optional	Enable web search. Default: true
max_iterations	integer	Optional	Max reasoning iterations. Default: 10
search_depth	integer	Optional	5 (quick), 15 (balanced), 30 (thorough)
visibility	string	Optional	"private" or "public" (marketplace)
category	string	Optional	Agent category for marketplace
tags	string[]	Optional	Searchable tags
tool_description	string	Optional	Description when this agent is used as a tool by other agents
settings	object	Optional	Additional agent settings
pricing	object	Optional	Pricing config for marketplace agents

Example: Create Agent

curl -X POST https://api.neura.ai/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "description": "Deep web research with citations",
    "model_id": "deepseek-ai/DeepSeek-V3.2",
    "use_web_search": true,
    "max_iterations": 15,
    "search_depth": 30,
    "system_prompt": "You are a thorough researcher. Always cite sources."
  }'

Response

JSON

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Research Agent",
  "description": "Deep web research with citations",
  "model_id": "deepseek-ai/DeepSeek-V3.2",
  "use_web_search": true,
  "max_iterations": 15,
  "created_at": "2025-01-15T10:30:00Z"
}

Agent Tools

Configure inference tools (image generation, TTS, video) and agent-as-tool capabilities.

GET/api/tools/inference?sync=false— List available inference tools. Pass sync=true to refresh from providers

POST/api/tools/sync— Sync latest tools from providers

GET/api/tools/agents— List agents available as tools

PUT/api/agents/{agent_id}/tools— Configure an agent's tool permissions

GET/api/agents/{agent_id}/tools— Get agent's current tool configuration

Tool Categories

Tools are grouped by model family. Categories include LLMs, image generators, and more.

DeepSeek

Reasoning and general-purpose LLMs

Llama

Meta's open-weight models

Qwen

Alibaba's multilingual models

FLUX / Stability

Image generation models

Configure Agent Tools

Parameter	Type	Required	Description
enable_agent_tools	boolean	Optional	Allow this agent to call other agents as tools
enable_inference_tools	boolean	Optional	Allow access to AI generation tools (images, audio, video)
auto_select_tools	boolean	Optional	Let the agent automatically select appropriate tools
selected_agent_ids	string[]	Optional	Specific agent IDs to enable as tools
selected_inference_tools	string[]	Optional	Specific inference tool names to enable

Example: Enable Tools

curl -X PUT https://api.neura.ai/api/agents/{agent_id}/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enable_inference_tools": true,
    "enable_agent_tools": true,
    "auto_select_tools": true
  }'

Inference Tools Response

JSON

{
  "categories": {
    "flux": [
      {
        "tool_id": "uuid-1234",
        "name": "black-forest-labs/FLUX.1-schnell",
        "display_name": "FLUX.1 Schnell",
        "description": "Fast high-quality image generation",
        "provider": "black-forest-labs",
        "model_id": "black-forest-labs/FLUX.1-schnell",
        "cost_per_call": 0.003,
        "output_price": 0.006,
        "cost_unit": "per_call",
        "max_duration_seconds": 300,
        "logo_url": "https://..."
      }
    ],
    "deepseek": [ // ... ],
    "llama": [ // ... ]
  },
  "total": 45
}

Chat & Streaming

Send messages to agents and receive responses via REST or real-time streaming.

POST/api/agents/{agent_id}/chat— Non-streaming chat (JWT auth)

POST/api/agents/{agent_id}/chat/stream— Streaming chat via SSE (JWT auth)

ⓘ

These endpoints use JWT Bearer token auth and are for platform users. For external integrations with API key auth, see the section.

Request Parameters

Parameter	Type	Required	Description
query	string	Required	The user message / prompt
model_id	string	Optional	Override the agent's default model. Default: deepseek-ai/DeepSeek-V3.2
kb_ids	string[]	Optional	Knowledge bases to search
conversation_history	object[]	Optional	Previous messages [{role, content}]
use_web_search	boolean	Optional	Enable web search. Default: true
max_iterations	integer	Optional	Max reasoning loops. Default: 10
search_depth	integer	Optional	5 (quick) / 15 (balanced) / 30 (thorough)
enable_inference_tools	boolean	Optional	Enable image/audio/video generation tools. Default: false
selected_inference_tools	string[]	Optional	Specific inference tool names to enable
enable_agent_tools	boolean	Optional	Enable calling other agents as tools. Default: false
selected_agent_ids	string[]	Optional	Specific agent IDs to enable as tools
auto_select_tools	boolean	Optional	Let the agent auto-select appropriate tools. Default: false
session_context	string	Optional	Temporary document context for this request
detailed_mode	boolean	Optional	Return additional agent metadata in response. Default: false

Non-Streaming Example

curl -X POST https://api.neura.ai/api/agents/{agent_id}/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key differences between RAG and fine-tuning?",
    "use_web_search": true,
    "search_depth": 15
  }'

Response

JSON

{
  "answer": "RAG (Retrieval-Augmented Generation) and fine-tuning serve different purposes...",
  "sources": ["https://arxiv.org/...", "https://docs.example.com/..."],
  "tool_calls": [{"tool": "web_search", "args": {"query": "RAG vs fine-tuning"}}],
  "iterations": 3,
  "costs": {
    "embedding_cost": 0.0001,
    "llm_cost": 0.0024,
    "search_cost": 0.001,
    "sandbox_cost": 0.0,
    "total_cost": 0.0035
  },
  // Additional fields for saved-agent chat:
  "agent_id": "a1b2c3d4-...",
  "agent_name": "Research Agent",
  "memories_used": 3,
  "instructions_active": 2,
  "context_loaded": true
}

Streaming (SSE) Example

ⓘ

The streaming endpoint returns Server-Sent Events. Each event is a JSON object prefixed with data: . See the section for all event types.

curl -N -X POST https://api.neura.ai/api/agents/{agent_id}/chat/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain quantum computing"}'

# Output (SSE stream):
# data: {"type":"status","message":"Agent loaded"}
# data: {"type":"token","content":"Quantum"}
# data: {"type":"token","content":" computing"}
# data: {"type":"done","answer":"Quantum computing...","costs":{...}}

Conversations

Manage persistent chat threads for your agents.

GET/api/agents/{agent_id}/conversations— List conversations (lightweight)

GET/api/agents/{agent_id}/conversations/{conversation_id}— Get full conversation with messages

POST/api/agents/{agent_id}/conversations— Create a conversation

PUT/api/agents/{agent_id}/conversations/{conversation_id}— Update conversation

DELETE/api/agents/{agent_id}/conversations/{conversation_id}— Delete conversation

Create Conversation

Parameter	Type	Required	Description
title	string	Required	Conversation title
messages	object[]	Required	Array of {role, content} messages
sandboxState	object	Optional	Sandbox session state (terminal, files, artifacts)

List Response

JSON

{
  "conversations": [
    {
      "id": "conv-uuid-1234",
      "title": "Research on AI trends",
      "messageCount": 12,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T11:45:00Z",
      "agentId": "agent-uuid-5678"
    }
  ]
}

Jobs & Tasks

Track and manage agent tasks with progress, sub-jobs, and lifecycle management.

GET/api/agents/{agent_id}/jobs— List jobs

POST/api/agents/{agent_id}/jobs— Create a job

GET/api/agents/{agent_id}/jobs/{job_id}— Get job details

PUT/api/agents/{agent_id}/jobs/{job_id}— Update job progress

DELETE/api/agents/{agent_id}/jobs/{job_id}— Delete job

GET/api/agents/{agent_id}/jobs/{job_id}/tree— Get job tree (parent + children)

GET/api/agents/{agent_id}/jobs/by-resource/{resource_id}— Get job by resource ID

POST/api/agents/{agent_id}/jobs/close-stale— Auto-close stale in_progress jobs

Create Job Parameters

Parameter	Type	Required	Description
name	string	Required	Job name
job_type	string	Optional	general, campaign, inference, research, automation, batch, pipeline
description	string	Optional	Detailed description
parent_job_id	string	Optional	Parent job UUID for sub-tasks
priority	integer	Optional	1-10, default: 5
total_steps	integer	Optional	Expected steps, default: 1
input_data	object	Optional	Input parameters for the job
bucket_id	string	Optional	Memory bucket UUID to associate
assigned_model	string	Optional	Model ID for this job
assigned_provider	string	Optional	Provider for this job
tags	string[]	Optional	Searchable tags

Job Statuses

pendingin_progresscompletedfailedpausedcancelled

List Jobs (with Filters)

Parameter	Type	Required	Description
status	string	Optional	Filter by status
job_type	string	Optional	Filter by type
parent_only	boolean	Optional	Only top-level jobs
limit	integer	Optional	Max results (default: 50)
offset	integer	Optional	Pagination offset

Dataset Creation Lab

Generate high-quality, validated Q&A datasets from any topic using a multi-agent pipeline: Analyzer → Researcher → Analyst → FactExtractor → Teacher → Critic → Export.

POST/api/datasets/pipeline/start— Start dataset creation pipeline

GET/api/datasets/pipeline/{job_id}/status— Get pipeline status

GET/api/datasets— List your datasets

Start Pipeline Parameters

Parameter	Type	Required	Description
topic	string	Required	The subject matter for dataset generation
job_name	string	Optional	Human-readable job name (defaults to "Dataset: {topic}")
target_samples	integer	Optional	Number of Q&A pairs to generate (default: 50)
data_source_mode	string	Optional	hybrid \| web_only \| scholarly_only \| hypothesis \| hypothesis_grounded \| user_docs_only
model_id	string	Optional	Base model for generation (default: deepseek-ai/DeepSeek-V3.2)
teacher_models	string[]	Optional	Specific teacher models to use
teacher_strategy	string	Optional	all_models \| round_robin \| parallel
pairs_per_source	integer	Optional	Q&A pairs per source document (default: 3)

Data Source Modes

hybridweb_onlyscholarly_onlyhypothesishypothesis_groundeduser_docs_only

Teacher Strategies

all_modelsround_robinparallel

Pipeline Stages

analyzingresearchinganalysisfact_extractionteachingcriticismexportingcompleted

curl -X POST https://api.neura.ai/api/datasets/pipeline/start \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Kubernetes pod scheduling and resource management",
    "target_samples": 100,
    "data_source_mode": "hybrid",
    "teacher_strategy": "all_models",
    "pairs_per_source": 5
  }'

Pipeline Status Response

json

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_name": "Dataset: Kubernetes pod scheduling",
  "status": "completed",
  "progress_percentage": 100,
  "current_stage": "completed",
  "actual_cost": 0.35,
  "created_at": "2026-02-23T10:30:00",
  "completed_at": "2026-02-23T10:45:00",
  "dataset": {
    "dataset_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "dataset_name": "Kubernetes pod scheduling - Dataset",
    "sample_count": 100,
    "total_tokens": 45000
  }
}

Knowledge Bases

Upload documents and create vector-indexed knowledge bases for RAG retrieval.

GET/api/agent/knowledge-bases— List your knowledge bases

POST/api/kb/upload— Upload document (multipart)

POST/api/datasets/{dataset_id}/enable-rag— Enable RAG indexing

GET/api/datasets/{dataset_id}/rag-status— Check RAG indexing status

Upload Document

ⓘ

File upload uses multipart/form-data instead of JSON. Supported formats: PDF, DOCX, TXT, MD, HTML.

curl -X POST https://api.neura.ai/api/kb/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "kb_id=kb-uuid-1234" \
  -F "file=@./document.pdf"

Instructions

Define standing rules, scheduled tasks, and conditional behaviors for your agents.

POST/api/agents/{agent_id}/instructions— Add an instruction

GET/api/agents/{agent_id}/instructions— List instructions

DELETE/api/agents/{agent_id}/instructions/{task_id}— Remove an instruction

Instruction Types

Standing

Always-active rules the agent follows (e.g., "Always respond in Spanish")

Scheduled

Recurring tasks with cron expressions (e.g., "Send daily report at 9am")

Conditional

Triggered by events (e.g., "Alert me when error rate exceeds 5%")

Add Instruction Parameters

Parameter	Type	Required	Description
instruction_type	string	Required	"standing", "scheduled", or "conditional"
action	string	Required	What the agent should do
trigger	string	Optional	For conditional: when to activate
schedule	string	Optional	For scheduled: cron expression (e.g., "0 9 * * *")
frequency	string	Optional	Human-readable: "hourly", "daily", "weekly"

Example: Add Standing Instruction

curl -X POST https://api.neura.ai/api/agents/{agent_id}/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction_type": "standing",
    "action": "Always include citations with URLs when referencing data"
  }'

List Response

JSON

{
  "agent_id": "a1b2c3d4-...",
  "agent_name": "Research Agent",
  "instructions": [
    {
      "task_id": "uuid-1234",
      "type": "standing",
      "action": "Always include citations with URLs",
      "trigger": null,
      "schedule": null,
      "frequency": null,
      "is_active": true,
      "execution_count": 47,
      "last_executed": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 1
}

Models

List available LLM models across all tiers.

GET/api/agent/models— List all available models

Model Providers

DeepInfra

Primary provider with wide model selection. DeepSeek, Llama, Qwen, Gemma, and more.

Atlas Cloud

Alternative provider with competitive pricing and low-latency inference.

Fine-tuned

Your custom trained models deployed from the Training page.

ⓘ

Use the model_id from this endpoint when creating or updating agents.

Response

JSON

{
  "models": [
    {
      "id": "deepseek-ai/DeepSeek-V3.2",
      "name": "DeepSeek V3.2",
      "provider": "deepseek-ai",
      "category": "deepseek",
      "context_length": 128000,
      "description": "Context: 128,000 tokens"
    },
    {
      "id": "meta-llama/Llama-3.3-70B-Instruct",
      "name": "Llama 3.3 70B Instruct",
      "provider": "meta-llama",
      "category": "llama",
      "context_length": 128000,
      "description": "Context: 128,000 tokens"
    }
  ],
  "default": "deepseek-ai/DeepSeek-V3.2"
}

Fine-Tuned Models

Access your custom trained models deployed on the Neura platform.

GET/api/agent/deployed-models— List your deployed fine-tuned models

GET/api/v1/models— List deployed models (OpenAI-compatible format)

Deployed Models Response

JSON

{
  "deployed_models": [
    {
      "model_id": "ft-abc123-my-model",
      "training_job_id": "tj-uuid-5678",
      "base_model": "meta-llama/Llama-3.3-70B-Instruct",
      "provider": "deepinfra",
      "dataset_name": "customer-support-qa",
      "completed_at": "2025-01-14T16:00:00Z"
    }
  ],
  "total": 1
}

Using Fine-Tuned Models

ⓘ

Fine-tuned models can be assigned to agents via the model_id field or used directly with the OpenAI-compatible endpoint.

# Use with an agent
curl -X PUT https://api.neura.ai/api/agents/{agent_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model_id": "ft-abc123-my-model"}'

OpenAI Compatible

Drop-in replacement for OpenAI API. Use your existing SDKs and tools.

POST/api/v1/chat/completions— Chat completions (OpenAI format)

GET/api/v1/models— List models (OpenAI format)

Request Parameters

Parameter	Type	Required	Description
model	string	Required	Model ID from /api/agent/models or deployed model ID
messages	object[]	Required	OpenAI message format [{role, content}]
max_tokens	integer	Optional	Max tokens. Default: 512
temperature	float	Optional	Sampling temperature. Default: 0.7
top_p	float	Optional	Nucleus sampling. Default: 0.9

Use with OpenAI SDK

curl -X POST https://api.neura.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V3.2",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 256,
    "temperature": 0.7
  }'

External Agent API

Let third parties interact with your agents via API keys.

POST/api/v1/agents/{agent_id}/chat— Chat with agent (API key auth)

POST/api/agents/{agent_id}/api-keys— Create API key

GET/api/agents/{agent_id}/api-keys— List API keys

DELETE/api/agents/{agent_id}/api-keys/{key_id}— Revoke API key

Chat Request

Parameter	Type	Required	Description
message	string	Required	The user message (alias: query)
query	string	Optional	Alternative to message — either field works
conversation_history	object[]	Optional	Previous messages [{role, content}] for context

Response

JSON

{
  "answer": "Based on the latest data, here are the key findings...",
  "sources": ["https://example.com/article1", "https://example.com/article2"],
  "usage": {
    "total_cost": 0.0035,
    "latency_ms": 1842
  }
}

Create API Key

Parameter	Type	Required	Description
key_name	string	Optional	Label for the key. Default: "Default"
rate_limit	integer	Optional	Requests per minute. Default: 60

Create Key Response

JSON

{
  "key_id": "uuid-5678",
  "key": "nk-abc123...",   // Only shown once!
  "key_name": "production",
  "rate_limit": 60,
  "endpoint": "https://api.neura.ai/api/v1/agents/{agent_id}/chat",
  "message": "API key created. Store it securely."
}

List Keys Response

JSON

{
  "keys": [
    {
      "key_id": "uuid-5678",
      "key_name": "production",
      "key_prefix": "nk-abc...",   // Never the full key
      "rate_limit": 60,
      "is_active": true,
      "created_at": "2025-01-15T10:30:00Z",
      "last_used": "2025-01-15T14:00:00Z"
    }
  ],
  "total": 1
}

ⓘ

The raw API key is only returned once at creation time. Store it securely. Subsequent list calls only show the key prefix.

Sandbox Sessions

Manage code execution sandbox state associated with agent conversations.

POST/api/agents/{agent_id}/sandbox-session— Save sandbox session state

GET/api/agents/{agent_id}/sandbox-session/{conversation_id}— Get sandbox session

DELETE/api/agents/{agent_id}/sandbox-session/{conversation_id}— Delete sandbox session

Save Session Parameters

Parameter	Type	Required	Description
conversation_id	string	Required	Conversation this sandbox belongs to
terminal_lines	object[]	Optional	Terminal output history
files	object[]	Optional	Files created in the sandbox
artifacts	object[]	Optional	Generated artifacts (HTML, images, etc.)
session	object	Optional	Session metadata (status, template, totalCost, runtimeMinutes)

Get Session Response

JSON

{
  "success": true,
  "session": {
    "session_id": "uuid-5678",
    "terminal_lines": [
      {"type": "command", "text": "python analyze.py"},
      {"type": "output", "text": "Processing 1000 records..."}
    ],
    "files": [
      {"name": "output.csv", "path": "/home/user/output.csv"}
    ],
    "artifacts": [
      {"type": "html", "title": "Dashboard", "content": "..."}
    ],
    "status": "running",
    "template": "python",
    "total_cost": 0.012,
    "runtime_minutes": 3.4,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z"
  }
}

API Usage Statistics

Monitor API consumption, costs, and performance metrics for your agents.

GET/api/agents/{agent_id}/api-usage— Get usage statistics

Query Parameters

Parameter	Type	Required	Description
period	string	Optional	"24h", "7d", or "30d". Default: "30d"

Response

JSON

{
  "period": "30d",
  "summary": {
    "total_requests": 1247,
    "total_tokens": 3842000,
    "total_cost": 4.82,
    "avg_latency_ms": 1340,
    "success_rate": 99.2,
    "error_count": 10,
    "last_request": "2025-01-15T14:30:00Z"
  },
  "daily": [
    {"date": "2025-01-15", "requests": 42, "cost": 0.18}
  ],
  "per_key": [
    {"key_id": "key-uuid", "key_name": "production", "requests": 800, "cost": 3.20}
  ]
}

SSE Stream Events

Event types emitted by streaming endpoints. Each line is prefixed with data: .

Event Type	Fields	Description
status	message: string	Connection and progress status updates
token	content: string	Streamed response token (append to output)
thinking	content: string	Agent reasoning / chain-of-thought
tool_call	tool: string, args: object	Tool invocation by the agent
tool_result	tool: string, result: object	Tool execution result
sources	sources: array	Retrieved references and citations
artifact	type: string, content: string	Generated artifact (HTML, image, etc.)
error	error: string	Error message
done	answer: string, costs: CostObject	Final response with cost breakdown

Cost Object

JSON

{
  "embedding_cost": 0.0001,    // Vector search embeddings
  "llm_cost": 0.0024,          // LLM inference
  "search_cost": 0.001,         // Web search (Tavily)
  "sandbox_cost": 0.005,        // Code execution sandbox
  "sub_agent_cost": 0.0,        // Calling other agents
  "inference_cost": 0.0,        // Image/audio generation
  "total_cost": 0.0085          // Sum of all costs
}

Error Handling

All errors follow a consistent format with appropriate HTTP status codes.

Error Response Format

JSON

{
  "error": "Human-readable error message",
  "detail": "Optional additional context"
}

Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Missing or invalid request parameters
401	Unauthorized	Missing or invalid authentication token
402	Payment Required	Insufficient credits balance
403	Forbidden	API key does not have access to this resource
404	Not Found	The requested resource does not exist
429	Too Many Requests	Rate limit exceeded for this API key
500	Internal Error	Unexpected server failure

Error Handling Example

# A 402 response when credits are exhausted:
curl -X POST https://api.neura.ai/api/agents/{agent_id}/chat \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "hello"}'

# HTTP/1.1 402 Payment Required
# {"error": "Insufficient credits", "detail": "Balance: $0.00"}

Rate Limits

API keys have configurable per-minute rate limits to protect your agents.

Default Limit

60 req/min

Configurable

Per Key

Error Code

429

Rate limits are set per API key at creation time via the rate_limit parameter. When exceeded, the API returns a 429 Too Many Requests response.

JSON

// 429 response when rate limited
{
  "error": "Rate limit exceeded: 61/60 per minute"
}

ⓘ

Platform API endpoints (JWT auth) have higher limits than external API key endpoints. Contact support for custom rate limits on high-volume integrations.

Neura Runtime

Run AI models locally on your device. Free, private, and offline-capable.

Installation

Two options — desktop app or CLI.

Desktop App (recommended for non-technical users)

Download from /download — one-click install with system tray, auto-connects to your browser.

CLI (developers)

bash

pip install neura-runtime
neura-runtime start

CLI Commands

bash

# Start the runtime daemon
neura-runtime start

# Check status
neura-runtime status

# Pair with your Neura account (6-digit code flow)
neura-runtime pair

# List detected local models (Ollama + LM Studio)
neura-runtime models

# List running Streamlit apps
neura-runtime apps

# Stop the daemon
neura-runtime stop

How It Works

Auto-detection: The Neura frontend polls localhost:9700/health every 5 seconds. When detected, your local models appear in the model selector.

Model discovery: Runtime queries Ollama (localhost:11434) and LM Studio (localhost:1234) for available models.

Inference: When you select a local model, chat completions are routed to your device via WebSocket tunnel. $0 cost.

Code execution: Python code runs in isolated Docker containers on your machine with strict sandboxing.

REST API (localhost:9700)

bash

# Health check
curl http://localhost:9700/health

# Full status (models, Docker, Streamlit apps)
curl http://localhost:9700/status

# Example response
{
  "version": "0.1.0",
  "docker_available": true,
  "local_models": [
    {
      "id": "local:ollama:llama3.2:latest",
      "name": "llama3.2:latest",
      "provider": "ollama",
      "parameter_size": "3B",
      "quantization": "q4_0"
    }
  ],
  "streamlit_apps": []
}

ⓘ

Local models work on all tiers, including free. Free tier users must use local runtime for all execution — no cloud fallback. Manage your runtime setup at /runtime in the dashboard.