# Web2 API Reference

> **Status**: WIP — Early Draft

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortensor.network/getting-started/web2-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.