API Reference

Complete documentation for all 100+ Adverant Nexus API endpoints

Authentication

API Key Authentication

All API requests require authentication using an API key. Include your API key in the request header:

# Using curl
curl -X POST http://localhost:9100/api/brain/memory/store \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Example memory"}'

# Using JavaScript fetch
fetch('http://localhost:9100/api/brain/memory/store', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: 'Example memory'
  })
})

Note: For local development, API key authentication is optional. In production, always use API keys and HTTPS.

Rate Limiting

API requests are rate limited to ensure fair usage:

Free tier: 100 requests per minute
Pro tier: 1,000 requests per minute
Enterprise: Custom limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704153600

Memory API

Store, recall, and search semantic memories with VoyageAI embeddings

Base URL: http://localhost:9100/api/brain/memory

POST/api/brain/memory/store

Store a new memory with embeddings

Parameters:

contentstringrequiredMemory content to store

tagsstring[]Tags for categorization

metadataobjectAdditional metadata

POST/api/brain/memory/recall

Recall memories using semantic search

Parameters:

querystringrequiredSearch query

limitnumberMax results (default: 10)

scoreThresholdnumberMin similarity score (0-1)

POST/api/brain/memory/search

Unified search across all memory types

Parameters:

querystringrequiredSearch query

filtersobjectFilter by type, tags, date range

limitnumberMax results (default: 20)

GET/api/brain/memory/list

List all stored memories with pagination

Parameters:

limitnumberResults per page (default: 20)

offsetnumberPagination offset

Vision API

Video processing, frame extraction, and scene detection

Base URL: http://localhost:9100/api/brain/videoagent

POST/api/brain/videoagent/submit-job

Submit video for processing

Parameters:

filenamestringrequiredVideo filename

videoUrlstringURL to video file

optionsobjectProcessing options

userIdstringUser ID for tracking

GET/api/brain/videoagent/status

Check video processing status

Parameters:

jobIdstringrequiredJob ID from submit-job

GET/api/brain/videoagent/result

Get completed video processing results

Parameters:

jobIdstringrequiredJob ID from submit-job

DELETE/api/brain/videoagent/cancel

Cancel a running video processing job

Parameters:

jobIdstringrequiredJob ID to cancel

Orchestrator API

Multi-agent task coordination and execution

Base URL: http://localhost:9100/api/brain/orchestrate

POST/api/brain/orchestrate/submit

Submit task for multi-agent orchestration

Parameters:

taskstringrequiredTask description

maxAgentsnumberMax agents (default: 3)

timeoutnumberTimeout in ms (default: 180000)

contextobjectAdditional context

GET/api/brain/orchestrate/status

Check orchestration task status

Parameters:

jobIdstringrequiredJob ID from submit

GET/api/brain/orchestrate/result

Get completed orchestration results

Parameters:

jobIdstringrequiredJob ID from submit

POST/api/brain/orchestrate/agent/collaborate

Multi-agent collaboration on complex tasks

Parameters:

objectivestringrequiredCollaboration objective

agentsarrayAgent configuration

iterationsnumberIterations (default: 2)

Documents API

Document processing, chunking, and retrieval

Base URL: http://localhost:9100/api/brain/fileprocess

POST/api/brain/fileprocess/submit-url

Submit document URL for processing

Parameters:

fileUrlstringrequiredDocument URL

filenamestringrequiredDocument filename

metadataobjectDocument metadata

userIdstringUser ID for tracking

POST/api/brain/fileprocess/submit-file

Submit document file for processing

Parameters:

filenamestringrequiredDocument filename

fileSizenumberFile size in bytes

mimeTypestringMIME type

metadataobjectDocument metadata

GET/api/brain/fileprocess/status

Check document processing status

Parameters:

jobIdstringrequiredJob ID from submit

POST/api/brain/fileprocess/store-document

Store document with intelligent chunking

Parameters:

contentstringrequiredDocument content

titlestringDocument title

metadataobjectDocument metadata

Geospatial API

Geocoding, coordinate transformation, and spatial analysis

Base URL: http://localhost:9100/api/brain/geospatial

POST/api/brain/geospatial/geocode

Convert address to coordinates

Parameters:

addressstringrequiredAddress to geocode

POST/api/brain/geospatial/reverse-geocode

Convert coordinates to address

Parameters:

latitudenumberrequiredLatitude

longitudenumberrequiredLongitude

POST/api/brain/geospatial/distance

Calculate distance between coordinates

Parameters:

fromobjectrequiredStart coordinates

toobjectrequiredEnd coordinates

unitstringkm or miles (default: km)

POST/api/brain/geospatial/proximity

Find points within radius

Parameters:

centerobjectrequiredCenter coordinates

radiusnumberrequiredRadius in km

pointsarrayrequiredPoints to check

Learning API

Progressive knowledge building and recall

Base URL: http://localhost:9100/api/brain/learning

POST/api/brain/learning/trigger

Trigger progressive learning on a topic

Parameters:

topicstringrequiredLearning topic

prioritynumberrequiredPriority 1-10

triggerstringrequiredTrigger reason

contextobjectAdditional context

POST/api/brain/learning/recall

Recall learned knowledge on a topic

Parameters:

topicstringrequiredTopic to recall

layerstringOVERVIEW|PROCEDURES|TECHNIQUES|EXPERT|all

maxResultsnumberMax results (default: 10)

Connect API

MCP tool execution and server management

Base URL: http://localhost:9100/api/brain/connect

POST/api/brain/connect/execute

Execute an MCP tool

Parameters:

toolstringrequiredTool name

parametersobjectrequiredTool parameters

GET/api/brain/connect/tools

List all available MCP tools

GET/api/brain/connect/servers

List all MCP servers

POST/api/brain/connect/server/add

Add a new MCP server

Parameters:

namestringrequiredServer name

configobjectrequiredServer configuration

Response Formats

Standard JSON Response

All API endpoints return JSON responses with the following structure:

{
  "success": true,
  "data": {
    // Response data
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2025-11-07T10:00:00Z",
    "processingTime": 123
  }
}

// Error response
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'query' parameter is required",
    "details": {}
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2025-11-07T10:00:00Z"
  }
}

Server-Sent Events (SSE) Streaming

Long-running operations support real-time progress updates via SSE:

// Connect to SSE stream
const eventSource = new EventSource(
  'http://localhost:9100/api/brain/orchestrate/stream?jobId=job_abc123'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Progress:', data);
};

// SSE event format
{
  "type": "progress",
  "jobId": "job_abc123",
  "state": "in_progress",
  "progress": 45,
  "message": "Agent 2/5 completed research phase",
  "metadata": {
    "agentId": "agent_xyz",
    "phase": "research"
  }
}

Error Codes

400 Bad Request

Invalid parameters or malformed request

401 Unauthorized

Missing or invalid API key

403 Forbidden

Insufficient permissions for this operation

404 Not Found

Resource not found

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Server error - please contact support

503 Service Unavailable

Service temporarily unavailable

Need help with integration?

Our team is here to help you build amazing AI-powered applications with Adverant Nexus.