Deeplogix - API Documentation

Architecture

Deeplogix exposes two independent services with different base URLs, authentication methods, and responsibilities.

Service	Base URL	Purpose	Authorization
API	`https://deeplogix.io/api`	Account management, model catalog, OAuth applications	JWT session (cookie), set automatically on login
Dispatcher	`https://deeplogix.io/dispatcher`	Model inference via WebSocket and HTTP proxy (Ollama, Triton)	Token from profile — see Authentication

Authentication

Authentication differs by service and connection type. Your token is available on the profile page under Connected Hosts → View Data → Host Token.

API — deeplogix.io/api

Session (cookie)

The API uses session-based authentication. Sign in via the platform UI — the JWT token is set automatically in a cookie and attached to all subsequent requests. No manual header is needed.

Dispatcher — WebSocket — browser / client

auth.token at socket init

Pass your token in the auth field when creating the Socket.IO connection:

const socket = io('https://deeplogix.io/dispatcher', {
  auth: { token: '<your_token>' }
})

Dispatcher — WebSocket — host / agent (Node.js)

extraHeaders.token at socket init

Pass your token in extraHeaders when connecting as a host:

const socket = io('https://deeplogix.io/dispatcher', {
  extraHeaders: { token: '<your_token>' }
})

Dispatcher — HTTP proxy (Ollama / Triton)

TOKEN header

Pass your token in the TOKEN request header (no "Bearer" prefix) along with HOST-ID:

TOKEN: <your_token>
HOST-ID: <your_host_id>

Quickstart — Dispatcher

Everything you need to start running inference through the Deeplogix Dispatcher.

01

Sign up

Create an account at deeplogix.io/app.

02

Copy your token

Open your profile → Connected Hosts → View Data and copy the token field. This token is required for every Dispatcher request.

03

Choose a host (optional)

Copy the host-id from the same page if you want to target a specific machine. If omitted, the Dispatcher picks an available host automatically.

Option 1 — Ollama HTTP API

Base URL: https://deeplogix.io/dispatcher/ollama/api/...
The Dispatcher proxies requests directly to the Ollama API — the request body format is identical to the official Ollama docs.

Generate (single prompt)

curl -X POST https://deeplogix.io/dispatcher/ollama/api/generate \
  --header 'token: <your_token>' \
  --header 'host-id: <your_host_id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "llama3.2:3b",
    "prompt": "You like bananas?",
    "stream": true
  }'

With "stream": true the response is NDJSON — one object per line:

// Each line is a separate JSON object
{"model":"llama3.2:3b","response":"Yes","done":false}
{"model":"llama3.2:3b","response":"!","done":true}

With "stream": false a single JSON object is returned with the full response.

Chat (with message history)

curl -X POST https://deeplogix.io/dispatcher/ollama/api/chat \
  --header 'token: <your_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "llama3.2:3b",
    "stream": false,
    "messages": [
      { "role": "user",      "content": "Hello!" },
      { "role": "assistant", "content": "Hi! How can I help?" },
      { "role": "user",      "content": "What is 2+2?" }
    ]
  }'

List models on the host

curl https://deeplogix.io/dispatcher/ollama/api/tags \
  --header 'token: <your_token>' \
  --header 'host-id: <your_host_id>'

Response follows the standard Ollama format: { "models": [ { "name", "size", "details", ... } ] }

Python example

import httpx

BASE_URL = "https://deeplogix.io/dispatcher"
HEADERS = {
    "token": "<your_token>",
    "host-id": "<your_host_id>",  # optional
    "Content-Type": "application/json"
}

response = httpx.post(
    f"{BASE_URL}/ollama/api/generate",
    headers=HEADERS,
    json={
        "model": "llama3.2:3b",
        "prompt": "You like bananas?",
        "stream": False
    }
)

print(response.json())

Option 2 — JSON-RPC

Call arbitrary methods on the host over a single HTTP endpoint.

curl -X POST https://deeplogix.io/dispatcher/json-rpc \
  --header 'token: <your_token>' \
  --header 'host-id: <your_host_id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "method": "your_method_name",
    "id": "req-1",
    "params": {}
  }'

Request body fields

Field	Type	Description
jsonrpc	string	Always `"2.0"`
method	string	Method name to call on the host
id	string \| number	Request identifier
params	object \| array \| null	Method parameters. If any required field is missing, returns `400` with the expected schema.

Headers reference

Header	Required	Description
token	Yes	Your token from profile → Connected Hosts → View Data
host-id	No	UUID of a specific host. If omitted, the Dispatcher selects an available host automatically.
Content-Type	Yes	`application/json`

Health

Monitor server, database, and Redis status. No authentication required.

GET /api/health Server, database, and Redis health ▼

Returns health status of the server and all connected services. Returns 200 when all services are healthy. Returns 503 when one or more services are unhealthy — the affected service entry will include an error field.

Responses

200 object All services healthy.

503 object One or more services unhealthy. Same structure with an error field on the failing service.

// 200 Response
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:00:00Z",
  "uptime": 3600,
  "services": {
    "database": { "status": "healthy", "latency": 12 },
    "redis": { "status": "healthy", "latency": 3 }
  }
}

GET /api/ Uptime check ▼

Simple uptime check. Returns a boolean status. No authentication required.

{ "status": true }

Public endpoints

Browse available models and providers. No authentication required.

GET /api/public/catalog List models ▼

Returns a filtered list of available models. All query parameters are optional.

Query Parameters

provider optional string Filter by provider name (e.g. "Ollama").

host_id optional uuid Filter by host identifier.

name optional string Filter by model name.

is_live optional boolean Filter to only live/active models. Pass true for production use.

// 200 Response
{
  "ok": true,
  "data": {
    "models": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "mistral-7b-instruct",
        "description": "Mistral 7B Instruct model",
        "host_id": "7c8d9e0f-1234-5678-abcd-ef0123456789",
        "host_name": "my-workstation",
        "provider": "Ollama",
        "ts_created": "2026-01-15T08:30:00Z",
        "is_living": true,
        "is_active": true
      }
    ],
    "count": 100,
    "limit": 10
  }
}

GET /api/public/model/{id} Get model details ▼

Returns detailed information about a specific model by its UUID.

Path Parameters

id required uuid Unique identifier of the model. Obtain from GET /api/public/catalog.

// 200 Response
{
  "ok": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "mistral-7b-instruct",
    "description": "Mistral 7B Instruct model",
    "host_id": "7c8d9e0f-1234-5678-abcd-ef0123456789",
    "host_name": "my-workstation",
    "provider": "Ollama",
    "ts_created": "2026-01-15T08:30:00Z",
    "is_living": true,
    "is_active": true
  }
}

GET /api/public/model-providers List providers ▼

Returns a list of all supported model providers available on the platform.

{
  "ok": true,
  "data": [
    { "provider": "Ollama" }
  ]
}

User & account

Manage your account and OAuth applications. Authentication via session cookie (set automatically on login).

GET /api/user/ Get current user ▼

Returns profile information for the currently authenticated user.

// 200 Response
{
  "ok": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "balance": 1200.50,
    "role": "user",
    "is_active": true
  }
}

GET /api/user/token Get Dispatcher token ▼

Returns the user's permanent Dispatcher token. This is the token used to authenticate WebSocket connections and HTTP proxy requests to the Dispatcher service.

// 200 Response
{
  "ok": true,
  "data": "<your_dispatcher_token>"
}

OAuth applications

Create and manage OAuth 2.0 applications for third-party integrations. Requires authentication.

GET /api/user/oauth List OAuth apps ▼

Returns all OAuth applications created by the authenticated user.

POST /api/user/oauth Create OAuth app ▼

Creates a new OAuth application. Returns a client_secret — store it securely as it cannot be retrieved again.

Request Body

name required string Display name of the OAuth application.

redirect_uris required string[] List of allowed redirect URIs (must be valid URIs).

scopes optional string[] List of permission scopes the application can request.

// 201 Response
{
  "ok": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "client_secret": "sk_live_..."
  }
}

POST /api/user/oauth/{id}/reset Reset client secret ▼

Resets and reissues the client_secret for the specified OAuth application. The previous secret is immediately invalidated.

WebSocket (Dispatcher)

The Dispatcher uses Socket.IO over WebSocket for real-time model inference. Connect as a client to send prompts and receive streamed responses, or as a host/agent to serve models from your machine.

Connection

Use the hostId and type query parameters. Client auth goes in auth; host auth goes in extraHeaders.

// Browser / client
const socket = io('https://deeplogix.io/dispatcher', {
  query: { hostId: '<your_host_id>', type: 'client' },
  auth: { token: '<your_token>' },
  transports: ['websocket']
})

// Host / agent (Node.js)
const socket = io('https://deeplogix.io/dispatcher', {
  query: { hostId: '<your_host_id>', type: 'host' },
  extraHeaders: { token: '<your_token>' },
  transports: ['websocket']
})

Event: ready

Emitted by the server immediately after a successful connection. Wait for this event before sending requests.

socket.on('ready', (ok) => {
  // ok === true — connection established, ready to send requests
})

Event: ping client only

Measure latency to the server and the connected host.

socket.emit('ping', Date.now(), ({ server_latency, agent_latency }) => {
  // server_latency — ms to the Dispatcher server
  // agent_latency — ms to the host; null if no hostId specified
})

Event: is_live client only

Check whether the connected host is currently online.

socket.emit('is_live', ({ result, retval }) => {
  // result: true/false — whether the check succeeded
  // retval: true — host is online, false — host is offline
})

Event: message — send client → server

Send an inference request. Two modes: generate (single prompt) and chat (conversation history).

// Generate — single prompt
socket.emit('message', {
  model: 'deepseek-r1:1.5b',
  prompt: 'Your prompt...'
})

// Chat — with conversation history
socket.emit('message', {
  type: 'chat',
  model: 'deepseek-r1:1.5b',
  messages: [
    { role: 'user', content: 'Your message' }
  ]
})

Event: message — receive server → client

The server streams response chunks. Parse data separately as it is a raw JSON string from the Ollama API.

socket.on('message', ({ id, data, isEnd }) => {
  // id — UUID of this request
  // data — JSON string from Ollama API (parse separately)
  // isEnd — true when the stream is complete
  const chunk = JSON.parse(data)
})

Host/agent events for agent developers

When connected as a host, your agent receives requests from the Dispatcher and responds with model lists and inference results.

// Host receives a request for its model list
socket.on('get_models', (clientSocketId) => {
  // respond with available models
  socket.emit('set_models', modelsObject)
})

// Host sends inference result back to a client
socket.emit('result', { socketId: clientSocketId, data: responseData })

HTTP Proxy (Dispatcher)

The Dispatcher also accepts direct HTTP requests as an alternative to WebSocket. All proxy requests require the TOKEN and HOST-ID headers.

Ollama proxy

Forwards requests to the Ollama instance running on the specified host. Request bodies follow the standard Ollama API format.

Method	Path	Description
POST	/dispatcher/ollama/api/generate	Generate (single prompt)
POST	/dispatcher/ollama/api/chat	Chat with history
GET	/dispatcher/ollama/api/tags	List available models on the host

// Example: generate via Ollama proxy
const res = await fetch('https://deeplogix.io/dispatcher/ollama/api/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'TOKEN': '<your_token>',
    'HOST-ID': '<your_host_id>'
  },
  body: JSON.stringify({ model: 'deepseek-r1:1.5b', prompt: 'Hello!' })
})

Triton proxy

Forwards requests to a Triton Inference Server running on the specified host. Supports the standard Triton HTTP API.

Method	Path
GET	/dispatcher/v2/health/live
GET	/dispatcher/v2/models/:model_name
GET / POST	/dispatcher/v2/repository/index
POST	/dispatcher/v2/models/:model_name/infer

# Python example — Triton proxy
import tritonclient.http as httpclient

TRITON_SERVER_URL = "deeplogix.io/dispatcher"

DISPATCHER_CREDENTIALS_HEADER = {
    "TOKEN": '<your_token>',
    "HOST-ID": '<your_host_id>'
}

client = httpclient.InferenceServerClient(
    url=TRITON_SERVER_URL,
    headers=DISPATCHER_CREDENTIALS_HEADER
)

Error reference

All errors return consistent JSON with a status code and error identifier. Error codes follow the pattern E_FIELD_NAME-ERROR_CODE.

Status	Code example	Description
200	—	Successful response. Returns `ok: true` and a `data` object.
400	E_HOST_ID_OR_TOKEN-INVALID	The request contains invalid parameters (e.g. a malformed UUID). Check field names and types.
401	E_TOKEN-ACCESS_DENIED	Token is missing or invalid. Ensure your token is correctly provided.
403	E_<FIELD>-FORBIDDEN	Authenticated but not permitted to access this resource.
404	E_HOST-NOT_FOUND	The requested resource does not exist. Verify the UUID or path parameter.
500	Internal Server Error	An unexpected server error occurred. If this persists, contact support.
503	Service Unavailable	One or more dependent services (database, Redis) are unhealthy. Check `GET /api/health` for details.

Deeplogix API