Web2 API Reference

Web2 RESTful API Reference

Status: WIP — Early Draft

This document provides a comprehensive reference for the RESTful API endpoints exposed by a Cortensor Router Node. These endpoints allow developers to interact with sessions, tasks, miners, and completions, enabling integration with AI inference workloads in Web2 applications.

---

Authentication

All endpoints require a Bearer token passed via the Authorization header:

Authorization: Bearer <api_key>

Default Dev Token: default-dev-token

---

Base URL

All requests are relative to the Router's base URL:

http://<router_host>:5010

For production, it is recommended to place the Router Node behind a reverse proxy (e.g. Nginx) for:

• TLS termination

• Rate limiting

• Load balancing

• Access control

• Hiding internal ports

---

Reverse Proxy (Production Setup)

For production environments, it is strongly recommended to run the Router Node behind a reverse proxy like Nginx, Caddy, or HAProxy. This enhances security, scalability, and performance. The reverse proxy should forward requests to the Router's internal address (e.g., 127.0.0.1:5010).

Benefits:

• TLS/SSL termination

• Request rate limiting

• Load balancing and retries

• Fine-grained access control

• IP whitelisting or firewall rules

• Prevents exposing internal ports to the public

---

Endpoints

GET /api/v1/info

Returns basic metadata about the Router Node.

curl -X GET http://<router_host>:5010/api/v1/info \
-H "Authorization: Bearer <api_key>"

---

GET /api/v1/status

Returns current router status and health.

curl -X GET http://<router_host>:5010/api/v1/status \
-H "Authorization: Bearer <api_key>"

---

GET /api/v1/miners

Lists all currently connected miner nodes.

curl -X GET http://<router_host>:5010/api/v1/miners \
-H "Authorization: Bearer <api_key>"

---

GET /api/v1/sessions

Lists all active sessions.

curl -X GET http://<router_host>:5010/api/v1/sessions \
-H "Authorization: Bearer <api_key>"

---

GET /api/v1/sessions/{sessionId}

Returns metadata about a specific session.

Path Param: sessionId — numeric session ID

curl -X GET http://<router_host>:5010/api/v1/sessions/0 \
-H "Authorization: Bearer <api_key>"

---

GET /api/v1/tasks/{sessionId}

Lists all tasks under a given session.

curl -X GET http://<router_host>:5010/api/v1/tasks/0 \
-H "Authorization: Bearer <api_key>"

---

GET /api/v1/tasks/{sessionId}/{taskId}

Returns a specific task from a session.

curl -X GET http://<router_host>:5010/api/v1/tasks/0/0 \
-H "Authorization: Bearer <api_key>"

---

POST /api/v1/completions/{sessionId}

Submit an AI inference prompt using a session ID in the URL.

Request Body:

{
  "prompt": "Hello, how are you?",
  "stream": false,
  "timeout": 60
}

curl -X POST http://<router_host>:5010/api/v1/completions/0 \
-H "Authorization: Bearer <api_key>" \
-d '{"prompt": "Hello, how are you?", "stream": false, "timeout": 60}'

---

POST /api/v1/completions

Submit a prompt with session ID included in the body.

Request Body:

{
  "session_id": 0,
  "prompt": "Hello, how are you?",
  "stream": false,
  "timeout": 60
}

curl -X POST http://<router_host>:5010/api/v1/completions \
-H "Authorization: Bearer <api_key>" \
-d '{"session_id": 0, "prompt": "Hello, how are you?", "stream": false, "timeout": 60}'

---

Streaming Completions

Setting stream: true in the request body returns real-time streamed responses using Server-Sent Events (SSE).

---

Error Codes

Code	Meaning
200	Success
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

---

Usage Notes

• Compatible with OpenAI-style interfaces

• Designed for Web2 integrations via REST

• Supports private/local inference routing