openapi: 3.1.0
info:
title: Network-AI Swarm Orchestrator
description: >
Multi-agent swarm orchestration API. Provides task delegation, shared
blackboard coordination, parallel agent spawning, and permission gating
via AuthGuardian. Requires the companion MCP server:
`npm install -g network-ai && npx network-ai-server --port 3001`
version: 4.11.2
license:
name: MIT
url: https://github.com/Jovancoding/Network-AI/blob/main/LICENSE
servers:
- url: http://localhost:3001
description: Local MCP server (default port)
paths:
/swarm/delegate:
post:
operationId: delegateTask
summary: Delegate a task to a sub-agent
description: >
Route a task to a specialized sub-agent within the swarm. Common agent
types: data_analyst, strategy_advisor, risk_assessor, orchestrator.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DelegateTaskRequest'
responses:
'200':
description: Task accepted and queued
content:
application/json:
schema:
$ref: '#/components/schemas/DelegateTaskResponse'
/swarm/state:
get:
operationId: querySwarmState
summary: Query current swarm state
description: >
Returns active tasks, blackboard contents, agent availability, and
permission grants.
parameters:
- name: scope
in: query
schema:
type: string
enum: [all, agents, tasks, blackboard, permissions]
default: all
description: Scope of state information to retrieve
- name: agentFilter
in: query
schema:
type: array
items:
type: string
description: Filter results to specific agent IDs
- name: includeHistory
in: query
schema:
type: boolean
default: false
description: Include historical task execution data
responses:
'200':
description: Current swarm state
content:
application/json:
schema:
$ref: '#/components/schemas/SwarmStateResponse'
/swarm/parallel:
post:
operationId: spawnParallelAgents
summary: Spawn multiple agents in parallel
description: >
Execute multiple sub-tasks simultaneously and synthesize results.
Useful for multi-perspective analysis.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ParallelAgentsRequest'
responses:
'200':
description: Synthesized results from all parallel agents
content:
application/json:
schema:
$ref: '#/components/schemas/ParallelAgentsResponse'
/auth/permission:
post:
operationId: requestPermission
summary: Request AuthGuardian permission
description: >
Gate access to protected resource types. Always call before DATABASE,
PAYMENTS, EMAIL, or FILE_EXPORT operations.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionRequest'
responses:
'200':
description: Permission decision
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionResponse'
/context/inject:
get:
operationId: injectContext
summary: Get project context for agent injection
description: >
Returns the persistent project context (Layer 3 memory) as a formatted
markdown block. Prepend this to any agent's system prompt so all agents
share the same long-term project awareness: goals, tech stack,
architecture decisions, milestones, and banned approaches.
responses:
'200':
description: Formatted project context block
content:
application/json:
schema:
type: object
properties:
contextMarkdown:
type: string
description: Markdown block ready to inject into system prompt
updatedAt:
type: string
description: ISO timestamp of last context update
/context/update:
post:
operationId: updateContext
summary: Update persistent project context
description: >
Persist a decision, milestone, stack entry, goal, or banned approach
to the project context file (Layer 3 memory). Changes survive across
all agent sessions — every future agent that calls injectContext will
see them.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateContextRequest'
responses:
'200':
description: Context section updated
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
section:
type: string
/blackboard/{key}:
operationId: readBlackboard
summary: Read a blackboard entry
parameters:
- name: key
in: path
required: true
schema:
type: string
description: Blackboard key (e.g. task:001:data_analyst)
responses:
'200':
description: Blackboard entry value (null if expired or not found)
content:
application/json:
schema:
type: object
properties:
key:
type: string
value: {}
expiresAt:
type: string
nullable: true
put:
operationId: updateBlackboard
summary: Write or update a blackboard entry
parameters:
- name: key
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BlackboardWriteRequest'
responses:
'200':
description: Write confirmed
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
previousValue: {}
/qa/harness:
post:
operationId: runQAHarness
summary: Run QA test harness
description: >
Run a batch of blackboard entries through the quality gate and return
aggregate results including pass rate, contradictions, and a regression snapshot.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QAHarnessRequest'
responses:
'200':
description: QA harness results
content:
application/json:
schema:
$ref: '#/components/schemas/QAHarnessResponse'
components:
schemas:
DelegateTaskRequest:
type: object
required: [targetAgent, taskPayload]
properties:
targetAgent:
type: string
description: Agent identifier (e.g. data_analyst, strategy_advisor)
taskPayload:
type: object
description: Task context, instructions, and required data
priority:
type: string
enum: [low, normal, high, critical]
default: normal
timeout:
type: number
default: 30000
description: Max execution time in milliseconds
requiresAuth:
type: boolean
default: false
DelegateTaskResponse:
type: object
properties:
taskId:
type: string
status:
type: string
result: {}
agentTrace:
type: array
items:
type: object
SwarmStateResponse:
type: object
properties:
timestamp:
type: string
activeAgents:
type: array
items:
type: object
pendingTasks:
type: array
items:
type: object
blackboardSnapshot:
type: object
permissionGrants:
type: array
items:
type: object
ParallelAgentsRequest:
type: object
required: [tasks]
properties:
tasks:
type: array
items:
type: object
required: [agentType, taskPayload]
properties:
agentType:
type: string
taskPayload:
type: object
synthesisStrategy:
type: string
enum: [merge, vote, chain, first-success]
default: merge
ParallelAgentsResponse:
type: object
properties:
synthesizedResult: {}
individualResults:
type: array
items:
type: object
executionMetrics:
type: object
PermissionRequest:
type: object
required: [resourceType, justification]
properties:
resourceType:
type: string
enum: [DATABASE, PAYMENTS, EMAIL, FILE_EXPORT]
justification:
type: string
description: Specific reason for access — must relate to the current task
scope:
type: string
description: Specific access scope (e.g. read:invoices)
PermissionResponse:
type: object
properties:
granted:
type: boolean
grantToken:
type: string
nullable: true
expiresAt:
type: string
nullable: true
restrictions:
type: array
items:
type: string
BlackboardWriteRequest:
type: object
required: [value]
properties:
value: {}
ttl:
type: number
description: Time-to-live in seconds (optional)
UpdateContextRequest:
type: object
required: [section]
properties:
section:
type: string
enum: [decisions, milestones, stack, goals, banned, project]
description: The context section to update
add:
description: Item to append (JSON object or plain string depending on section)
set:
type: object
description: Key-value pairs to merge (used for stack and project sections)
complete:
type: string
description: Milestone name to mark completed (milestones section only)
QAHarnessRequest:
type: object
required: [scenarios]
properties:
scenarios:
type: array
items:
type: object
required: [id, key, value, sourceAgent]
properties:
id:
type: string
key:
type: string
value: {}
sourceAgent:
type: string
minScore:
type: number
qualityThreshold:
type: number
description: Global minimum quality score (0-1). Defaults to 0.7.
QAHarnessResponse:
type: object
properties:
total:
type: integer
passed:
type: integer
failed:
type: integer
passRate:
type: number
contradictions:
type: array
items:
type: object
properties:
key:
type: string
agentA:
type: string
agentB:
type: string
snapshot:
type: object
properties:
timestamp:
type: string
scenariosRun:
type: integer
scenarioPassRate:
type: number