Skip to Content

API Reference

Complete API reference for the isA Model Service.

Base URL: http://localhost:8082

Authentication

All requests require an API key via the Authorization header or X-API-Key header:

RBAC: When RBAC_ENABLED=true, each endpoint additionally requires a specific resource:action permission in the JWT. See RBAC for the full permission matrix.

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8082/api/v1/models

Inference

POST /api/v1/invoke

Unified inference endpoint. Supports chat completions, streaming, tool calling, and structured outputs.

curl -X POST http://localhost:8082/api/v1/invoke \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": false
  }'

Request Body:

FieldTypeRequiredDescription
modelstringYesModel identifier
messagesarrayYesChat messages array
streambooleanNoEnable streaming (default: false)
toolsarrayNoTool definitions for function calling
tool_choicestringNoTool selection strategy
response_formatobjectNoStructured output schema
temperaturenumberNoSampling temperature (0-2)
max_tokensintegerNoMaximum tokens to generate

Response:

{
  "id": "chatcmpl-abc123",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}

POST /api/v1/invoke/v2

Extended invoke route with additional routing and observability features.

GET /api/v1/models

List available LLM models across all configured providers.

curl http://localhost:8082/api/v1/models

Response:

{
  "models": [
    {"id": "gpt-4o-mini", "provider": "openai"},
    {"id": "claude-sonnet-4-5-20250929", "provider": "anthropic"},
    {"id": "llama3.2", "provider": "ollama"}
  ]
}

Providers

The Model Service routes requests to the appropriate provider based on the model identifier:

ProviderModelsConfig Variable
OpenAIgpt-4o, gpt-4o-mini, gpt-4.1-*OPENAI_API_KEY
Anthropicclaude-*ANTHROPIC_API_KEY
OpenRouteranthropic/*, deepseek/*, openai/*, 200+ modelsOPENROUTER_API_KEY
Anthropic Subclaude-* (via subscription proxy)ANTHROPIC_SUB_PROXY_URL
Ollamallama*, mistral*, codellama*Local (no key needed)
Cerebrascerebras-*CEREBRAS_API_KEY
YYDSyyds-*YYDS_API_KEY
Replicatereplicate/*REPLICATE_API_TOKEN

Providers documentation

Caching

GET /api/v1/cache/stats

Cache hit/miss statistics for L1 (exact) and L2 (semantic) caches.

curl http://localhost:8082/api/v1/cache/stats

POST /api/v1/cache/invalidate/{provider}/{model}

Invalidate cache entries for a specific provider and model.

curl -X POST http://localhost:8082/api/v1/cache/invalidate/openai/gpt-4o-mini

POST /api/v1/cache/clear

Clear all cache entries.

curl -X POST http://localhost:8082/api/v1/cache/clear

Caching documentation

Training

POST /api/v1/models/training/train

Start a Lightning training pipeline.

curl -X POST http://localhost:8082/api/v1/models/training/train \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "closed_loop",
    "dataset_id": "my-dataset",
    "config": {
      "epochs": 10,
      "learning_rate": 0.001
    }
  }'

Supported Algorithms:

AlgorithmDescription
closed_loopFeedback loop optimization
apoAutomatic prompt optimization
grpoGroup relative policy optimization
customCustom training pipeline

GET /api/v1/models/training/stats

Training job statistics and progress.

POST /api/v1/models/training/export

Export training data and artifacts.

GET /api/v1/models/training/config

Read the active training configuration.

Prediction (ML)

Generic machine learning prediction endpoints for time-series forecasting and custom models.

POST /api/v1/models/training/ml/prediction/models

Create and train a prediction model.

curl -X POST http://localhost:8082/api/v1/models/training/ml/prediction/models \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-sales-forecast",
    "model_type": "prophet",
    "data": [
      {"ds": "2026-01-01", "y": 120},
      {"ds": "2026-01-02", "y": 125},
      {"ds": "2026-01-03", "y": 130}
    ]
  }'

Request Body:

FieldTypeRequiredDescription
namestringYesModel display name
model_typestringYesModel type (prophet)
dataarrayYesTraining data with ds (date) and y (value) keys

GET /api/v1/models/training/ml/prediction/models

List prediction models. Supports pagination.

ParameterTypeDescription
limitintegerMax results (default: 20)
offsetintegerSkip N results (default: 0)

GET /api/v1/models/training/ml/prediction/models/{model_id}

Get prediction model details including training status.

DELETE /api/v1/models/training/ml/prediction/models/{model_id}

Delete a prediction model and its artifacts.

POST /api/v1/models/inference/ml/prediction/models/{model_id}/predict

Run a prediction (forecast).

curl -X POST http://localhost:8082/api/v1/models/inference/ml/prediction/models/{model_id}/predict \
  -H "Content-Type: application/json" \
  -d '{
    "periods": 14,
    "frequency": "D",
    "include_history": false
  }'
FieldTypeRequiredDescription
periodsintegerYesNumber of periods to forecast
frequencystringYesFrequency (D, W, M, H)
include_historybooleanNoInclude historical data in response

GET /api/v1/models/inference/ml/prediction/models/{model_id}/predictions

List prediction runs for a model. Supports pagination (limit, offset).

Sleep Intelligence

Sleep intelligence routes are mounted under /api/v1/sleep and are used by the commercial sleep model products.

POST /api/v1/sleep/evaluate

Evaluate sleep quality and related sleep-health signals.

curl -X POST http://localhost:8082/api/v1/sleep/evaluate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "user_id": "user_123",
    "mode": "fast",
    "session_data": {
      "duration_min": 430,
      "stage_durations": {
        "W": 32,
        "N1": 48,
        "N2": 210,
        "N3": 72,
        "REM": 68
      },
      "movement_score": 0.18
    }
  }'

POST /api/v1/sleep/recommend

Generate recommendations from sleep evaluation inputs or model outputs.

curl -X POST http://localhost:8082/api/v1/sleep/recommend \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "user_id": "user_123",
    "sleep_history": [
      {
        "business_date": "2026-05-16",
        "quality_score": 7.2,
        "stage_distribution": {
          "n1": 0.12,
          "n2": 0.49,
          "n3": 0.17,
          "rem": 0.16,
          "wake": 0.06
        }
      }
    ],
    "goals": ["improve_quality"],
    "context": {
      "screen_time_before_bed_min": 90
    }
  }'

Registered commercial model products include com_sleep_quality, com_sleep_stage, and com_health_risk.

Voice & Realtime

POST /realtime/sessions

Create a new realtime voice session. Returns a WebSocket URL for bidirectional audio streaming.

curl -X POST http://localhost:8082/realtime/sessions \
  -H "Content-Type: application/json" \
  -H "x-user-id: user-123" \
  -d '{
    "model": "gpt-4o-realtime-preview",
    "voice": "alloy",
    "instructions": "You are a helpful assistant",
    "metadata": {"session_type": "support"}
  }'

Response:

{
  "session_id": "sess_abc123",
  "websocket_url": "ws://localhost:8082/realtime/ws/sess_abc123?token=sess_abc123",
  "expires_at": "2026-03-02T12:15:00Z",
  "model": "gpt-4o-realtime-preview",
  "voice": "alloy"
}

GET /realtime/ws/{session_id}

WebSocket endpoint for bidirectional voice streaming. Proxies between client and upstream realtime API with event normalization, privacy filtering, and metrics collection.

Session config sent upstream:

  • Modalities: ["text", "audio"]
  • Audio format: pcm16
  • Turn detection: server_vad (threshold 0.5, silence duration 200ms)
  • Input transcription: whisper-1

POST /realtime/sessions/{session_id}/interrupt

Send a barge-in signal to cancel the current response and clear the audio buffer.

curl -X POST http://localhost:8082/realtime/sessions/sess_abc123/interrupt

Intelligent Model Routing

POST /api/v1/invoke/v2

Extended invoke route with role-based resolution, capability filtering, and cost-aware ranking.

Additional request fields (beyond standard /invoke):

FieldTypeDescription
rolestringAgent role (reasoning, response, coding, default)
preferred_max_latency_msnumberSoft latency constraint
preferred_max_cost_per_tokennumberSoft cost constraint

Resolution priority:

  1. Explicit model + provider in request
  2. Role-based defaults (see table below)
  3. Capability-filtered candidates ranked by cost
  4. Service type defaults

Service type defaults:

Service TypeDefault ModelProvider
textgpt-4o-miniopenai
visiongpt-5-miniopenai
audiowhisper-1openai
imageflux-schnellreplicate
embeddingtext-embedding-3-smallopenai

Multi-Modal Support

The invoke endpoint supports multi-modal inputs depending on the provider and model:

ModalityDescriptionExample Models
TextStandard chat completionsAll models
VisionImage understandinggpt-4o, claude-*
AudioSpeech-to-text, text-to-speechwhisper-*
EmbeddingVector embeddingstext-embedding-*
ImageImage generationdall-e-*, replicate/*
VideoVideo understandingreplicate/*

Python Client

from isa_model import AsyncISAModel
 
async with AsyncISAModel(base_url="http://localhost:8082") as client:
    # Chat completion
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)
 
    # Streaming
    async for chunk in await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Tell me a story"}],
        stream=True
    ):
        print(chunk.choices[0].delta.content or "", end="")

Billing & Usage Endpoints

GET /api/v1/usage

Query credit balance and per-meter consumption. Requires billing:read permission.

curl "http://localhost:8082/api/v1/usage?since=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Metering & Usage API for full parameter reference and response schema.

GET /api/v1/audit

Query the immutable audit log for all write operations and auth events. Requires audit_logs:read permission.

curl "http://localhost:8082/api/v1/audit?resource=agents&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

See Audit Logging for full parameter reference.

DELETE /api/v1/tenants/{id}

GDPR cascading tenant deletion — removes all data for the tenant across PG, Redis, Qdrant, and NATS. Requires orgs:admin permission.

curl -X DELETE "http://localhost:8082/api/v1/tenants/tenant_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "tenant_id": "tenant_abc123",
  "status": "deletion_scheduled",
  "estimated_completion": "2026-03-27T14:05:00Z"
}

Deletion is async — data is soft-deleted immediately and hard-deleted by the weekly cleanup CronJob.

POST /api/v1/tenants/{id}/gdpr-delete

Trigger immediate GDPR hard delete (bypasses the weekly CronJob). Requires orgs:admin permission.

curl -X POST "http://localhost:8082/api/v1/tenants/tenant_abc123/gdpr-delete" \
  -H "Authorization: Bearer YOUR_API_KEY"

Environment Variables

VariableRequiredDescription
OPENAI_API_KEYFor OpenAI modelsOpenAI provider key
ANTHROPIC_API_KEYFor Claude modelsAnthropic provider key
OPENROUTER_API_KEYFor OpenRouter modelsOpenRouter provider key
ANTHROPIC_SUB_PROXY_URLFor subscription proxyLocal proxy URL (default: http://localhost:5005/v1)
YYDS_API_KEYFor YYDS modelsYYDS provider key
REDIS_URLFor cachingRedis connection URL
QDRANT_URLFor semantic cacheQdrant connection URL
NATS_URLFor eventsNATS connection URL
Home