🤖 Agent AI API

Dedicated endpoint to use Neuralai Agent AI from your applications: create, run and manage your agents and read the execution history. Requires an API key with the agents scope (opt-in, selectable in API Hub → API Keys).

📡 Endpoint

POST https://app.neuralaiweb.com/functions/agentApi
Authentication & scope

🔑 agents scope required

The key must have the "agents" scope (opt-in, not preselected at creation): it enables execution, creation, update, deletion of agents and history reading. The key is verified via SHA-256: always send it in clear in the header or body, never its hash.

# Header (consigliato)
x-api-key: nai_...

# oppure nel body JSON
{ "api_key": "nai_...", "operation": "list_agents" }
Operations

operation field in the JSON body. Write = modifies your agents (requires the agents scope).

👁️

list_agents

List your agents

—

👁️

get_agent

Full agent detail

agent_id

✍️

create_agent

Create a custom agent

name, role, synthesis, general_prompt, …

✍️

update_agent

Partial update (also status, api_key_id)

agent_id + campi

✍️

delete_agent

Delete an agent

agent_id

👁️

execute

Run the agent (task or playground)

agent_id, input, mode?, session_id?

👁️

list_tasks

Execution history (AgentTask)

agent_id?, limit? (max 100)

👁️

get_task

Single execution with full result

task_id

Examples

1) Run an agent (final result in history)

const res = await fetch("https://app.neuralaiweb.com/functions/agentApi", {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": "nai_..." },
  body: JSON.stringify({
    operation: "execute",
    agent_id: "ag_xxx",
    input: "Prepara il preventivo per il cliente Rossi",
    mode: "task"
  })
});
const data = await res.json();
// { success: true, response: "...", task_id: "...",
//   tokens_consumed: 15, elapsed_s: 4 }

2) Create an agent

{
  "operation": "create_agent",
  "name": "Preventivi Acme",
  "role": "preventivi",
  "synthesis": "Genera preventivi professionali dal listino",
  "general_prompt": "Sei il consulente commerciale di Acme…",
  "welcome_message": "",
  "icon_emoji": "🧾",
  "dynamic_mode": false,
  "doc_folders": ["Listini"],
  "web_folders": [],
  "kb_ids": [],
  "direct_files": [],
  "api_key_id": ""
}

Limits (as in the app): name 60, synthesis 200, role 60, general prompt 20,000, welcome 500 chars; max 20 doc folders, 20 web folders, 5 KBs, 50 direct files. Direct files must already be in Neuralai storage (upload via apiUploadFile): external URLs are rejected (SSRF protection) and Knowledge Bases must belong to the key owner.

3) History and playground

// Cronologia (origin "api")
{ "operation": "list_tasks", "agent_id": "ag_xxx", "limit": 20 }
{ "operation": "get_task", "task_id": "task_xxx" }

// Playground: chat con sessione persistente
{ "operation": "execute", "agent_id": "ag_xxx",
  "input": "Ciao, presenta le tue funzioni", "mode": "playground" }
// → { session_id: "...", response: "..." }
// ripeti con session_id per continuare la conversazione
Tokens & attribution
  • Same pricing as in the app: 15 tokens per run, 30 if the knowledge context exceeds 40,000 chars, +5 if the agent has dynamic behavior. Atomic charge on the owner's NeuralAI balance, with automatic refund if the model fails.
  • Attribution: API executions are attributed to the key used in the request (usage log, API Hub → Stats). If an agent has an associated key (api_key_id field, settable via API or from the agent drawer), executions made FROM THE APP (playground, tasks, scheduled) are attributed to that key.
Security
  • Isolation: each key sees and modifies ONLY the agents of its owner (key-owner check on every operation).
  • SSRF protection: direct files accept only Neuralai storage URLs (media.base44.com, base44.app, storage.googleapis.com/neuralai-canvas-sites bucket).
  • The agent's knowledge is wrapped in dedicated delimiters and treated as data, not instructions (prompt injection resistance).
  • Store the key server-side (environment variables or Secret Manager), never in client code: see the API Key Security section.