Universitas AI
API Request Access

API Documentation

Reference for the Socrates API — verified intelligence, stateful reasoning, deep inference, and private agent networks.

API Status: Operational

Quick Navigation

Overview Core Concepts Authentication Endpoints Code Examples Error Handling

Overview

The Socrates API provides programmatic access to Universitas AI's intelligence stack — verified research, stateful reasoning sessions, deep inference via Sigma (Σ), and agent-to-agent coordination for private IAIA networks.

The API is designed for enterprise and institutional deployment. It is available by request. Access credentials are issued through the sales process.

Base URL: https://api.universitas.ai/v2

Current Version: v2

Format: JSON over HTTPS

Core Concepts

Verified Intelligence

Every response from Socrates is grounded in verified institutional sources — PubMed, arXiv, SEC filings, NASA, and more. The Chain-of-Provenance system attaches a full citation trail to every claim at every reasoning step. Responses include a citations array with source metadata so you can audit the evidence behind any output.

Stateful Sessions

Socrates maintains context across queries within a session. Pass a session_id to continue a research thread — the API builds on prior queries, resolves ambiguity using accumulated context, and surfaces connections across the session history. Sessions persist until explicitly closed or after inactivity timeout.

Sigma (Σ) — Deep Inference

Sigma is Universitas AI's inaugural reasoning model. Set "mode": "sigma" to activate multi-step analytical reasoning. Sigma synthesizes across sources, cross-validates findings, and returns a reasoning_trace — an auditable chain of inference steps alongside the final answer.

Combine Sigma with a stateful session for deep inference that compounds over time — each query builds on the reasoning history of the session.

Agent-to-Agent (A2A)

The /agents endpoints enable programmatic orchestration of multi-agent workflows. Enterprise customers can provision private IAIA (Internet of AI Agents) networks — isolated, verified agent systems scoped entirely to their organization.

Chain-of-Provenance Stateful Sessions Sigma / Deep Inference A2A Coordination Private IAIA Networks

Authentication

All API requests require a bearer token issued at account provisioning. Pass your token in the Authorization header on every request.

Authorization: Bearer sk_uat_your_api_key_here

Keys are scoped to your organization and environment (production vs. staging). Keep keys server-side — never expose them in client-side code. To request access or rotate a key, contact sales@universitas.ai.

Key Scopes

Scope Description
research:read Query research endpoints and retrieve results
sessions:write Create and manage stateful sessions
sigma:invoke Access the Sigma deep inference model
agents:admin Provision and orchestrate A2A agent networks

Endpoints

POST /v2/research

Submit a research query. Optionally attach a session for stateful context and activate Sigma for deep inference.

Request body:

{
  "query":      string,      // required — natural language research query
  "session_id": string,      // optional — attach to a stateful session
  "mode":       string,      // optional — "standard" (default) or "sigma"
  "provenance": boolean,     // optional — include Chain-of-Provenance (default: true)
  "sources":    string[],    // optional — filter by source set
  "limit":      integer      // optional — max results (default: 10)
}

Response:

{
  "answer":          string,       // synthesized response
  "reasoning_trace": object[],     // inference steps (sigma mode only)
  "citations":       object[],     // verified source references
  "session_context": object,       // updated session state
  "results":         object[],     // individual source results
  "processing_time": string
}

Parameters:

Parameter Type Required Description
query string Yes Natural language research query
session_id string No Attach to an existing stateful session
mode string No standard or sigma (deep inference)
provenance boolean No Include Chain-of-Provenance citations (default: true)
sources array No Source filter e.g. ["pubmed","arxiv","sec"]

POST /v2/sessions

Create a new stateful session. Returns a session_id to pass in subsequent research queries.

{
  "label":   string,    // optional — human-readable session name
  "domain":  string,    // optional — domain hint e.g. "oncology", "finance"
  "ttl":     integer    // optional — session TTL in seconds
}

GET /v2/sessions/{session_id}

Retrieve session state, history, and accumulated context for an active session.

DELETE /v2/sessions/{session_id}

Explicitly close and purge a session. All session context is deleted.

POST /v2/agents

Provision an agent within your IAIA network. Requires agents:admin scope. Enterprise only.

{
  "role":       string,     // agent domain e.g. "oncology-researcher"
  "network_id": string,     // your private IAIA network identifier
  "config":     object      // agent-specific configuration
}

GET /v2/status

Returns API operational status, version, and your account's active session count.

Error Handling

All error responses use a consistent envelope:

{
  "error": {
    "code":    "INVALID_QUERY",
    "message": "The search query cannot be empty",
    "details": "Provide a non-empty query string"
  },
  "request_id": "req_8f3a29d1c4b2",
  "timestamp":  "2026-03-28T14:30:00Z"
}

Common error codes:

Code HTTP Status Description
UNAUTHORIZED 401 Missing or invalid API key
FORBIDDEN 403 Key does not have the required scope
INVALID_QUERY 400 Empty or malformed request body
SESSION_NOT_FOUND 404 Session ID does not exist or has expired
RATE_LIMITED 429 Request volume exceeds your plan limits
INTERNAL_ERROR 500 Server-side processing error

Code Examples

Python

import requests

API_BASE = "https://api.universitas.ai/v2"
HEADERS  = {
    "Authorization": "Bearer sk_uat_your_key_here",
    "Content-Type":  "application/json"
}

# Create a stateful session
session = requests.post(f"{API_BASE}/sessions", headers=HEADERS,
    json={"label": "oncology-research", "domain": "pharma"}).json()

session_id = session["session_id"]

# Stateful query with Sigma deep inference
response = requests.post(f"{API_BASE}/research", headers=HEADERS,
    json={
        "query":      "KRAS G12C inhibitor resistance mechanisms",
        "session_id": session_id,
        "mode":       "sigma",
        "provenance": True,
        "sources":    ["pubmed", "arxiv"]
    }).json()

print(response["answer"])

for citation in response["citations"]:
    print(f"  [{citation['source']}] {citation['title']}")

# Continue the session — context is preserved
followup = requests.post(f"{API_BASE}/research", headers=HEADERS,
    json={
        "query":      "What combination therapies show most promise?",
        "session_id": session_id,
        "mode":       "sigma"
    }).json()

print(followup["answer"])

JavaScript

const API_BASE = 'https://api.universitas.ai/v2';
const HEADERS  = {
  'Authorization': 'Bearer sk_uat_your_key_here',
  'Content-Type':  'application/json'
};

async function research(query, sessionId, mode = 'standard') {
  const res = await fetch(`${API_BASE}/research`, {
    method:  'POST',
    headers: HEADERS,
    body: JSON.stringify({
      query,
      session_id: sessionId,
      mode,
      provenance: true
    })
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`${err.error.code}: ${err.error.message}`);
  }

  return res.json();
}

// Create session then query
async function run() {
  const session = await fetch(`${API_BASE}/sessions`, {
    method: 'POST', headers: HEADERS,
    body: JSON.stringify({ label: 'my-research-session' })
  }).then(r => r.json());

  const result = await research(
    'mechanisms of antibiotic resistance in Gram-negative bacteria',
    session.session_id,
    'sigma'
  );

  console.log(result.answer);
  result.citations.forEach(c => console.log(` — ${c.title} [${c.source}]`));
}

run();

cURL

# Create a session
curl -X POST https://api.universitas.ai/v2/sessions \
  -H "Authorization: Bearer sk_uat_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"label": "research-session", "domain": "life-sciences"}'

# Query with Sigma and Chain-of-Provenance
curl -X POST https://api.universitas.ai/v2/research \
  -H "Authorization: Bearer sk_uat_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query":      "CRISPR off-target effects in therapeutic applications",
    "session_id": "sess_8f3a29d1",
    "mode":       "sigma",
    "provenance": true,
    "sources":    ["pubmed", "arxiv"]
  }'

# Check API status
curl https://api.universitas.ai/v2/status \
  -H "Authorization: Bearer sk_uat_your_key_here"

Support

API access is provisioned through our enterprise onboarding process. For documentation questions, integration support, or access requests: