Getting Started

Node Management

Models

Tasks & Inference

Streaming

API Reference

Detailed specifications for the edge node orchestration API. Use the sidebar to navigate through endpoints.

Node Management

GET /api/v1/health

Retrieves the current diagnostic state of the node. Used by the Master server's load balancer to determine if the node is healthy enough to receive tasks.

Query Parameters

verbose boolean • optional
If true, includes detailed CPU core metrics and thermal data (if available on the hypervisor).
200 OK
401 Auth Error
{
  "status": "operational",
  "version": "3.2.1",
  "system": {
    "uptime_sec": 849210,
    "ram_used_mb": 2104,
    "ram_total_mb": 4096,
    "cpu_load_1m": 0.45
  },
  "models_loaded": 1
}

Models

POST /api/v1/models/load

Instructs the node to download (if not cached) and load a HuggingFace transformer model into memory. This is a blocking operation and may take several seconds.

Body Parameters (JSON)

model_id string • required
The exact HuggingFace repository ID. Example: sentence-transformers/all-MiniLM-L6-v2.
quantization string • optional
Desired precision. Enum: fp32, fp16, int8. Default: int8. Lower precision saves RAM at the cost of slight accuracy loss.
force_reload boolean • optional
If true, clears the local model cache and re-downloads the weights from the hub.
 
curl -X POST https://node.csasq.ru/api/v1/models/load \
  -H "Authorization: Bearer secret_token" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "BAAI/bge-small-en-v1.5",
    "quantization": "fp16"
  }'
200 OK
{
  "success": true,
  "model_id": "BAAI/bge-small-en-v1.5",
  "load_time_ms": 1450,
  "vram_allocated_mb": 340
}

Tasks & Inference

POST /api/v1/tasks/ingest

Submits a synchronous batch of URLs for immediate scraping, sanitization, and vectorization. For large datasets, use the WebSocket stream instead.

Body Parameters

urls array of strings • required
List of target web addresses. Max 50 per request.
extract_rules object • optional
Custom CSS selectors to define the article body, overriding the default readability algorithm. E.g., {"main_content": "article.post"}.
200 OK
{
  "batch_id": "tsk_99x81",
  "results": [
    {
      "url": "https://example.com",
      "status": "success",
      "tokens": 412,
      "vector": [0.012, -0.045, 0.112, "... (381 more)"]
    }
  ]
}

Streaming Pipeline

WSS /api/v1/ws

The core pipeline interface. Establishes a persistent, multiplexed WebSocket connection for high-throughput streaming of task instructions and binary vector responses.

Data Processing & Traffic Shaping Notice

Because the node transmits raw arrays of 32-bit floats (tensor embeddings) back over this socket in binary frames (rather than JSON strings), the outbound traffic will be dense, continuous, and highly randomized (resembling high-entropy encrypted payloads like AI Platform traffic).

This is normal, expected behavior for mathematical tensor serialization. It is critical that upstream firewalls and Data Processing engines do not throttle this endpoint, as it will break the inference pipeline.

Connection Protocol

  1. Client initiates HTTP GET to /api/v1/ws with Connection: Upgrade and Upgrade: websocket headers.
  2. Client must include Authorization: Bearer <token> in the initial request headers.
  3. Upon 101 Switching Protocols, the client streams JSON frames containing URL arrays.
  4. The node responds asynchronously with binary WebSocket frames representing the Float32 arrays.

Client Tx (JSON Frame)

{
  "action": "enqueue",
  "targets": ["https://news.ycombinator.com"]
}

Server Rx (Binary Frame)

[Binary Float32 Array Buffer]
Length: 1536 bytes (384 dimensions)