# Web2 API Reference

> **Status**: WIP — Early Draft

This document provides a comprehensive reference for the RESTful API endpoints exposed by a [Cortensor Router Node](https://docs.cortensor.network/getting-started/installation-and-setup/router-node-setup). 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:

```http
Authorization: Bearer <api_key>
```

**Default Dev Token:** `default-dev-token`

***

### Base URL

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

```http
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](https://docs.cortensor.network/getting-started/installation-and-setup/router-node-setup/reverse-proxy-setup) (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.

```bash
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.

```bash
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.

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

***

#### GET /api/v1/sessions

Lists all active sessions.

```bash
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

```bash
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.

```bash
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.

```bash
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:**

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

```bash
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:**

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

```bash
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