Agentics API v1

Authentication #authentication

All API requests require authentication using an API key passed in the Authorization header. Tokens come in three flavours.

API Key Authentication

bashCopycurl https://api.agentics.co.za/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Sigma", "messages": [{"role": "user", "content": "Hello!"}]}'

JWT Authentication

For user sessions, JWT tokens are issued on login with a 7-day expiry. Refresh tokens last 30 days.

Hardware Authentication

Device-bound authentication is available for enhanced security. Contact support to enable hardware ID binding.

Rate Limits #rate-limits

Soft limits scale with subscription tier. Hard limits protect upstream infrastructure. Both reset every 60 seconds. Inspect headers X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Limit.

Base URL #base-url

All API requests should be made to:

urlCopyhttps://api.agentics.co.za

The API follows REST conventions and returns JSON responses.

SDKs #sdks

Two official SDKs wrap the entire Agentics API behind a single typed client. Both expose the same 32 resource groups, share the AGENTICS_API_KEY convention, and target the same base URL. The TypeScript SDK adds a Realtime voice client for the Orb.

Install matrix

Resource groups (shared)

Both clients expose these 32 groups. TypeScript uses camelCase accessors (client.inference), Go uses PascalCase fields (client.Inference).

TypeScript SDK #sdk-typescript

The official TypeScript / Node SDK. Ships dual ESM and CommonJS builds with full type declarations. Requires Node 18 or newer. Published as agentics-sdk.

Install

bashCopy# From the public npm registry
npm install agentics-sdk

# Or straight from Agentics, no registry account needed
npm install agentics-sdk --registry https://agentics.co.za/npm

# Or pin the exact tarball
npm install https://agentics.co.za/npm/agentics-sdk/-/agentics-sdk-0.2.1.tgz

Initialise

jsCopyimport Agentics from 'agentics-sdk';

const client = new Agentics({
  apiKey: process.env.AGENTICS_API_KEY
});

const res = await client.inference.chat({
  model: 'Sigma',
  messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(res.choices[0].message.content);

Streaming

jsCopyconst stream = await client.inference.chat({
  model: 'Sigma',
  messages: [{ role: 'user', content: 'Write a poem' }],
  stream: true
});

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

Realtime voice (Orb)

The Realtime client streams microphone audio to the Orb and receives turns and generated audio back, either directly or via the desktop Companion.

jsCopyimport { RealtimeClient } from 'agentics-sdk/realtime';

const orb = new RealtimeClient({
  token: process.env.AGENTICS_API_KEY,
  transport: 'auto'
});

orb.on('turn', (turn) => console.log(turn.role, turn.text));
await orb.connect();

Every resource

All 32 groups hang off the client instance - client.audio.textToSpeech(...), client.images.generate(...), client.embeddings.search(...), client.wallet, client.hosting, client.affiliate and the rest listed in the SDKs overview.

Go SDK #sdk-go

The official Go SDK. Module path agentics.co.za/sdk, served straight from this site over the Go module proxy protocol - no GitHub, no git host required.

Install

bashCopygo get agentics.co.za/sdk

Initialise

goCopypackage main

import (
  "context"
  "fmt"
  "os"

  agentics "agentics.co.za/sdk"
  "agentics.co.za/sdk/option"
)

func main() {
  client := agentics.NewClient(
    option.WithAPIKey(os.Getenv("AGENTICS_API_KEY")),
  )

  res, err := client.Inference.Chat(context.Background(), agentics.ChatParams{
    Model: "Sigma",
    Messages: []agentics.ChatMessage{
      {Role: "user", Content: "Hello!"},
    },
  })
  if err != nil {
    panic(err)
  }
  fmt.Println(res.Choices[0].Message.Content)
}

Environment

NewClient reads these automatically when set, so an explicit option is optional.

Streaming

goCopystream := client.Inference.ChatStreaming(ctx, agentics.ChatParams{
  Model:    "Sigma",
  Messages: msgs,
})
defer stream.Close()

for stream.Next() {
  chunk := stream.Current()
  fmt.Print(chunk.Choices[0].Delta.Content)
}
if err := stream.Err(); err != nil {
  panic(err)
}

Every service

All 32 groups are fields on the client - client.Audio, client.Images, client.Embeddings, client.Wallet, client.Hosting, client.Affiliate and the rest from the SDKs overview. Pointer helpers agentics.String, agentics.Int, agentics.Bool, agentics.Float64 build optional fields.

Chat Completions #chat

The primary inference endpoint. Generate text responses using our AI models. Compatible with OpenAI's chat completions API, with one extra field: tools_async for fire-and-forget background tool calls.

Request Body

jsonCopy{
  "model": "Sigma",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "maxTokens": 1024,
  "temperature": 0.7
}

Parameters

Streaming Response

jsCopyconst response = await fetch('https://api.agentics.co.za/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'Sigma',
    messages: [{ role: 'user', content: 'Write a poem' }],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Models #models

List available AI models and their capabilities.

List Models

httpCopyGET /v1/models

Get Model Info

httpCopyGET /v1/models/:model

Available Models

Image Generation #images

27 image models behind one endpoint. Flux, SDXL, AgenPics, Arta, Juggernaut, Dreamshaper and more. Set model in the request body to pick one.

Request Body

jsonCopy{
  "prompt": "A futuristic cityscape at sunset",
  "model": "flux",
  "size": "1024x1024",
  "n": 1
}

Parameters

Audio Processing #audio

Text-to-speech and speech-to-text capabilities powered by local ONNX models. 71 voices, streaming PCM at 44.1 kHz, sub-200ms first audio.

Text-to-Speech

jsonCopy{
  "text": "Hello, welcome to Agentics!",
  "voice": "female2",
  "speed": 1.2,
  "quality": 20,
  "outputBase64": true
}

Parameters

Available Voices

Four signature voices: Justine (default, warm), Emma (clinical, fast), Lucas (deep, calm), Felix (playful, conversational). Plus 67 community voices behind voice=community/<handle>.

httpCopyGET /v1/audio/voices

Speech-to-Text

JSON Request

jsonCopy{
  "audioData": "base64_encoded_audio",
  "language": "en"
}

Multipart Form Request

bashCopycurl https://api.agentics.co.za/v1/audio/stt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F file="@audio.wav" \
  -F language="en"

Live Transcription (WebSocket)

Stream audio in real-time for continuous transcription with VAD (Voice Activity Detection) and EOT (End-of-Turn) detection.

Query Parameters

Embeddings #embeddings

384-dimensional GTE-Small embeddings. Up to 1,024 inputs per request. The same backend powers NRN. Returns the standard OpenAI shape, with optional cosine similarity scoring against a stored corpus via compare_to.

Generate Embedding

httpCopyPOST /v1/embeddings/generate

jsonCopy{
  "text": "The quick brown fox"
}

Add to Group

httpCopyPOST /v1/embeddings/add

jsonCopy{
  "group": "documentation",
  "content": "How to use the API",
  "metadata": "optional metadata string"
}

Search Embeddings

httpCopyPOST /v1/embeddings/search

jsonCopy{
  "query": "How do I use the API?",
  "group": "documentation",
  "limit": 5
}

List Groups

httpCopyGET /v1/embeddings/groups

Delete Group

httpCopyDELETE /v1/embeddings/groups/:name

Agent Tools #agent

Execute agentic tools for advanced AI capabilities including code execution, web search, and more. Agentics is the first inference API with first-class async tools.

Available Tools

Endpoint

httpCopyPOST /v1/agent/execute

Realtime Voice (Orb) #realtime

Live voice interface with bidirectional audio streaming. Send 16 kHz PCM frames, receive PCM frames at 44.1 kHz. Includes voice activity detection, interruption handling, and a structured event channel for tool calls.

The Orb provides a voice-powered AI interaction with:

• Real-time speech recognition
• Natural language understanding
• Text-to-speech responses
• Interrupt handling
• Tool calling over the structured event channel

Conversations #conversations

Manage persistent conversation history.

Endpoints

httpCopyGET    /v1/conversations           # List conversations
POST   /v1/conversations           # Create conversation
GET    /v1/conversations/:id       # Get conversation
DELETE /v1/conversations/:id       # Delete conversation
POST   /v1/conversations/:id/messages  # Add message

Memory Storage #memory

Key-value storage for persistent agent memory.

Endpoints

httpCopyGET    /v1/memory/:key    # Get value
POST   /v1/memory         # Set value
DELETE /v1/memory/:key    # Delete value

NRN - Neural Resonance Network #nrn

A biologically-inspired memory system written in C that learns, reinforces, decays, and consolidates knowledge over time. NRN is the core long-term memory engine powering Agentics AI agents, designed to solve the fundamental problem of information retention across unbounded time spans.

How It Works

NRN uses a 384-dimensional embedding space (GTE-Small ONNX, compiled directly into the binary) combined with Hebbian learning, temporal decay, and a learned neural controller. Knowledge that is accessed frequently becomes permanent; unused knowledge decays naturally. Semantic clusters form automatically, and cross-cluster associations strengthen through co-retrieval.

Endpoints

Push a memory into the Neural Resonance Network. NRN handles deduplication, association building, and decay automatically.

Query NRN with a natural language prompt. Returns ranked, weighted memories with adaptive retrieval that improves with use.

Architecture

Retrieval Strategies

The neural controller selects from 4 strategies per query:

Configuration

CLI Usage

bashCopy# Prepare documents for ingestion
nrn prep ./docs/ prepared.txt

# Add embeddings to a user's group
nrn add main docs prepared.txt

# Search with neuroplastic retrieval
nrn search main docs "how does authentication work" 5

# Run consolidation (merge duplicates, decay, bridge)
nrn consolidate main docs

# Get memory stats
nrn stats main docs

# Give reward feedback (improves controller)
nrn reward main docs 412 0.9

# Prune decayed memories below threshold
nrn prune main docs

Why NRN

Traditional RAG systems treat every retrieval identically - no learning, no adaptation, no memory lifecycle. NRN introduces neuroplastic principles:

• Memories that matter are reinforced and become permanent
• Unused knowledge gracefully decays, keeping the index clean
• Semantic clustering enables cross-topic associative recall
• The neural controller learns which retrieval strategy works best per query type
• Consolidation merges duplicates and generates bridging knowledge between clusters
• Zero runtime dependencies - the ONNX model is embedded in the compiled C binary

MCP Protocol #mcp

Model Context Protocol integration for connecting AI agents to external tools and data sources.

Endpoints

httpCopyGET    /v1/mcp/servers    # List MCP servers
POST   /v1/mcp/connect    # Connect to server
POST   /v1/mcp/execute    # Execute MCP tool

WebGrep Search #webgrep

Lightning-fast web search and content extraction.

Endpoints

httpCopyPOST /v1/webgrep/search    # Web search
POST /v1/webgrep/fetch     # Fetch URL content
POST /v1/webgrep/rag       # RAG-mode extraction

Search Engines

• DuckDuckGo (default)
• Google
• Brave
• Kagi
• Startpage
• Ecosia

Workflow Engine #workflow

Agentic Flow - orchestrate complex multi-step workflows.

Endpoints

httpCopyPOST   /v1/workflow/create    # Create workflow
POST   /v1/workflow/execute   # Execute workflow
GET    /v1/workflow/:id       # Get workflow status

Agentics CLI #cli

Full-featured AI agent CLI with live voice chat.

Installation

bashCopynpm install -g agentics

Usage

bashCopy# Start chat
agentics

# With specific model
agentics --model Sigma

# Voice mode
agentics --voice

# With tools enabled
agentics --tools

Features

• Live voice chat with WebSocket streaming
• Silero VAD with smart end-of-turn detection
• Local ONNX-powered text-to-speech
• Image generation with Flux and Arta
• 10+ integrated tools
• 18 text models + 27 image models

Taskman #taskman

AI-powered task management with MCP server integration.

Installation

bashCopynpm install -g @agentics/taskman

Modes

bashCopy# Terminal UI
taskman tui

# Background daemon
taskman daemon

# MCP server
taskman mcp

# AI reminders
taskman reminder

MCP Tools

18 integrated tools for task operations accessible via Agentics CLI and other MCP clients.

Agentics Studio #studio

Web-based development platform at ur1s.xyz.

Features

• Custom subdomain on ur1s.xyz
• Built-in HTML/CSS/JS editor
• Real-time visit analytics
• Instant deployment and updates

VPN Access #vpn

On-demand VPN credentials for secure browsing and access.

Endpoints

httpCopyGET    /v1/vpn/servers       # List available servers
POST   /v1/vpn/credentials   # Get connection credentials
GET    /v1/vpn/config        # Download configuration file

Supported Protocols

• OpenVPN
• WireGuard
• IKEv2

Error Handling #errors

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

jsonCopy{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Common Error Codes