Index your code with Devin

[DeepWiki](https://deepwiki.com/)

[DeepWiki](https://deepwiki.com/)

[YouROK/TorrServer](https://github.com/YouROK/TorrServer "Open repository")

Index your code with

Devin
Edit WikiShare

Last indexed: 28 February 2026 ( [d26699](https://github.com/YouROK/TorrServer/commits/d266990f))

- [Overview](https://deepwiki.com/YouROK/TorrServer/1-overview)
- [System Architecture](https://deepwiki.com/YouROK/TorrServer/2-system-architecture)
- [Backend System](https://deepwiki.com/YouROK/TorrServer/3-backend-system)
- [Server Initialization and Lifecycle](https://deepwiki.com/YouROK/TorrServer/3.1-server-initialization-and-lifecycle)
- [BitTorrent Engine (BTServer)](https://deepwiki.com/YouROK/TorrServer/3.2-bittorrent-engine-(btserver))
- [Cache and Storage System](https://deepwiki.com/YouROK/TorrServer/3.3-cache-and-storage-system)
- [Reader and Priority Management](https://deepwiki.com/YouROK/TorrServer/3.4-reader-and-priority-management)
- [Torrent Management API](https://deepwiki.com/YouROK/TorrServer/3.5-torrent-management-api)
- [Web Server and Middleware](https://deepwiki.com/YouROK/TorrServer/3.6-web-server-and-middleware)
- [Static Asset Serving](https://deepwiki.com/YouROK/TorrServer/3.7-static-asset-serving)
- [Streaming and Playback](https://deepwiki.com/YouROK/TorrServer/3.8-streaming-and-playback)
- [REST API Reference](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference)
- [Optional Services](https://deepwiki.com/YouROK/TorrServer/3.10-optional-services)
- [Database and Persistence](https://deepwiki.com/YouROK/TorrServer/3.11-database-and-persistence)
- [Frontend System](https://deepwiki.com/YouROK/TorrServer/4-frontend-system)
- [Application Bootstrap and PWA](https://deepwiki.com/YouROK/TorrServer/4.1-application-bootstrap-and-pwa)
- [Build System and Asset Pipeline](https://deepwiki.com/YouROK/TorrServer/4.2-build-system-and-asset-pipeline)
- [Component Architecture](https://deepwiki.com/YouROK/TorrServer/4.3-component-architecture)
- [Torrent Management UI](https://deepwiki.com/YouROK/TorrServer/4.4-torrent-management-ui)
- [Torrent Details and Cache Visualization](https://deepwiki.com/YouROK/TorrServer/4.5-torrent-details-and-cache-visualization)
- [Settings and Configuration UI](https://deepwiki.com/YouROK/TorrServer/4.6-settings-and-configuration-ui)
- [Internationalization and Localization](https://deepwiki.com/YouROK/TorrServer/4.7-internationalization-and-localization)
- [Search Integration](https://deepwiki.com/YouROK/TorrServer/4.8-search-integration)
- [Configuration and Settings](https://deepwiki.com/YouROK/TorrServer/5-configuration-and-settings)
- [Command-Line Arguments](https://deepwiki.com/YouROK/TorrServer/5.1-command-line-arguments)
- [BitTorrent Configuration](https://deepwiki.com/YouROK/TorrServer/5.2-bittorrent-configuration)
- [Network and Proxy Settings](https://deepwiki.com/YouROK/TorrServer/5.3-network-and-proxy-settings)
- [Security and Authentication](https://deepwiki.com/YouROK/TorrServer/5.4-security-and-authentication)
- [Cache and Storage Configuration](https://deepwiki.com/YouROK/TorrServer/5.5-cache-and-storage-configuration)
- [External Service Configuration](https://deepwiki.com/YouROK/TorrServer/5.6-external-service-configuration)
- [Deployment and Installation](https://deepwiki.com/YouROK/TorrServer/6-deployment-and-installation)
- [Linux Installation](https://deepwiki.com/YouROK/TorrServer/6.1-linux-installation)
- [macOS Installation](https://deepwiki.com/YouROK/TorrServer/6.2-macos-installation)
- [Docker Deployment](https://deepwiki.com/YouROK/TorrServer/6.3-docker-deployment)
- [Platform-Specific Considerations](https://deepwiki.com/YouROK/TorrServer/6.4-platform-specific-considerations)
- [Development Guide](https://deepwiki.com/YouROK/TorrServer/7-development-guide)
- [Building from Source](https://deepwiki.com/YouROK/TorrServer/7.1-building-from-source)
- [Project Structure](https://deepwiki.com/YouROK/TorrServer/7.2-project-structure)
- [Backend Development](https://deepwiki.com/YouROK/TorrServer/7.3-backend-development)
- [Frontend Development](https://deepwiki.com/YouROK/TorrServer/7.4-frontend-development)
- [Testing and CI/CD](https://deepwiki.com/YouROK/TorrServer/7.5-testing-and-cicd)
- [Contributing Guidelines](https://deepwiki.com/YouROK/TorrServer/7.6-contributing-guidelines)

Menu

# REST API Reference

Relevant source files

- [server/docs/docs.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/docs/docs.go)
- [server/docs/swagger.json](https://github.com/YouROK/TorrServer/blob/d266990f/server/docs/swagger.json)
- [server/docs/swagger.yaml](https://github.com/YouROK/TorrServer/blob/d266990f/server/docs/swagger.yaml)
- [server/settings/torrent.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/settings/torrent.go)
- [server/torr/dbwrapper.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/dbwrapper.go)
- [server/torr/stream.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/stream.go)
- [server/torr/utils/webImageChecker.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/utils/webImageChecker.go)
- [server/utils/location.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/utils/location.go)
- [server/web/api/cache.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/cache.go)
- [server/web/api/m3u.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/m3u.go)
- [server/web/api/route.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/route.go)
- [server/web/api/settings.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/settings.go)
- [server/web/api/storage.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/storage.go)
- [server/web/api/stream.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/stream.go)
- [server/web/api/torrents.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/torrents.go)
- [server/web/api/upload.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/upload.go)
- [server/web/api/utils/testlink.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/utils/testlink.go)
- [server/web/api/viewed.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api/viewed.go)
- [server/web/auth/auth.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/auth/auth.go)
- [server/web/pages/route.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/pages/route.go)
- [web/src/utils/Hosts.js](https://github.com/YouROK/TorrServer/blob/d266990f/web/src/utils/Hosts.js)

This page provides a complete reference for TorrServer's REST API endpoints. The API enables programmatic control of torrent streaming, including adding/removing torrents, querying status, configuring settings, and streaming content via HTTP.

For information about streaming protocols (DLNA, WebDAV, FUSE), see [Additional Interfaces](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#3.12). For HTTP streaming implementation details, see [Streaming and Playback](https://deepwiki.com/YouROK/TorrServer/3.8-streaming-and-playback). For web server configuration and middleware, see [Web Server and Middleware](https://deepwiki.com/YouROK/TorrServer/3.6-web-server-and-middleware).

## API Overview

TorrServer exposes a RESTful HTTP API built with the Gin web framework. All endpoints return JSON responses (except streaming endpoints which return media content). The API is documented using OpenAPI/Swagger annotations and includes interactive documentation at `/swagger/`.

**Sources:** [server/web/server.go40-51](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L40-L51)

## Base Configuration

### URL Structure

```
http://{host}:{port}/api/{resource}
https://{host}:{sslport}/api/{resource}
```

Default ports:

- HTTP: `8090` (configurable via `--port`)
- HTTPS: `8091` (configurable via `--sslport`)

**Sources:** [server/web/server.go99-124](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L99-L124)

### Authentication

The API supports HTTP Basic Authentication when enabled via database settings. Authentication is enforced by the `auth.SetupAuth()` middleware.

```
Authorization: Basic <base64(username:password)>
```

**Sources:** [server/web/server.go78](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L78-L78)

### Middleware Stack

```

HTTP Request

log.WebLogger()

blocker.Blocker()

gin.Recovery()

cors.New()

location.Default()

auth.SetupAuth()

Route Handler

HTTP Response
```

**Sources:** [server/web/server.go77-78](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L77-L78)

## API Endpoint Categories

### Endpoint Overview Table

| Category | Base Path | Purpose | Authentication |
| --- | --- | --- | --- |
| Torrent Management | `/api/torrents` | Add, list, edit, remove torrents | Optional |
| Cache & Status | `/api/cache`, `/api/stat` | Query cache state and torrent status | Optional |
| Streaming | `/stream/{hash}/{id}`, `/play/{hash}/{id}` | Stream torrent content via HTTP | Optional |
| Settings | `/api/settings` | Get/set BitTorrent configuration | Optional |
| Search | `/api/search` | Search torrents via Torznab/RuTor | Optional |
| System | `/echo`, `/shutdown`, `/viewed` | System utilities | Optional |
| Documentation | `/swagger/*` | Interactive API documentation | None |

**Sources:** [server/web/server.go80-96](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L80-L96)

## Endpoint Hierarchy Diagram

```

/

/api

/stream

/play

/swagger

/echo

/torrents
POST,GET

/torrent/*
Actions

/settings
GET,POST

/cache
GET

/search
GET

/shutdown
GET

/upload

/drop

/list

/set

/rem

/preload

/viewed

{hash}/{id}

{hash}/{id}

/*any
```

**Sources:** [server/web/server.go80-96](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L80-L96) [server/web/api package referenced](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api%20package%20referenced)

## Core API Endpoints

### Torrent Management

#### Add Torrent - POST `/api/torrents`

Adds a new torrent from magnet link, torrent file, or hash.

**Request Body (JSON):**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | Yes | Always `"add"` |
| `link` | string | Conditional | Magnet URI or HTTP(S) URL to .torrent file |
| `hash` | string | Conditional | InfoHash (hex string) if torrent exists in DB |
| `torrent` | string | Conditional | Base64-encoded .torrent file content |
| `title` | string | No | Display title for torrent |
| `poster` | string | No | URL to poster image |
| `data` | string | No | Custom metadata (JSON string) |
| `category` | string | No | Category/genre classification |
| `save` | boolean | No | Save torrent to database (default: true) |

**Response (JSON):**

Returns a `TorrentStatus` object (see [Common Response Structures](https://github.com/YouROK/TorrServer/blob/d266990f/Common%20Response%20Structures)).

**Example Request:**

```
{
  "action": "add",
  "link": "magnet:?xt=urn:btih:...",
  "title": "Example Movie",
  "poster": "https://example.com/poster.jpg",
  "save": true
}
```

**Sources:** [server/torr/apihelper.go40-81](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L40-L81)

#### List Torrents - GET `/api/torrents`

Returns all torrents (active in memory + stored in database).

**Response (JSON):**

```
[\
  {\
    "stat": 2,\
    "stat_string": "Working",\
    "hash": "abc123...",\
    "name": "Example Torrent",\
    "title": "Example Movie",\
    "loaded_size": 1234567890,\
    "torrent_size": 2345678901,\
    "preload_size": 104857600,\
    "preloaded_bytes": 52428800,\
    "download_speed": 1048576.5,\
    "upload_speed": 262144.2,\
    "total_peers": 45,\
    "active_peers": 12,\
    "connected_seeders": 8,\
    "file_stats": [...]\
  }\
]
```

**Sources:** [server/torr/apihelper.go183-207](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L183-L207) [server/torr/torrent.go302-386](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L302-L386)

#### Edit Torrent - POST `/api/set`

Updates torrent metadata (title, poster, category, data).

**Request Body (JSON):**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `hash` | string | Yes | Torrent InfoHash (hex) |
| `title` | string | No | New title |
| `poster` | string | No | New poster URL |
| `category` | string | No | New category |
| `data` | string | No | New custom metadata |

**Response (JSON):**

Returns updated `TorrentStatus` object.

**Sources:** [server/torr/apihelper.go120-159](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L120-L159)

#### Drop Torrent - POST `/api/drop`

Removes torrent from memory but keeps it in database.

**Request Body (JSON):**

```
{
  "hash": "abc123..."
}
```

**Response:** HTTP 200 OK

**Sources:** [server/torr/apihelper.go209-212](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L209-L212) [server/torr/torrent.go274-282](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L274-L282)

#### Delete Torrent - POST `/api/rem`

Permanently removes torrent from both memory and database, optionally deleting cache files.

**Request Body (JSON):**

```
{
  "hash": "abc123..."
}
```

**Response:** HTTP 200 OK

**Sources:** [server/torr/apihelper.go161-181](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L161-L181) [server/torr/torrent.go283-300](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L283-L300)

### Cache & Status

#### Cache State - GET `/api/cache`

Returns detailed cache state for a specific torrent, including piece-level information.

**Query Parameters:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `hash` | string | Yes | Torrent InfoHash (hex) |

**Response (JSON):**

```
{
  "capacity": 1073741824,
  "filled": 536870912,
  "pieces_length": 4194304,
  "pieces_count": 256,
  "hash": "abc123...",
  "pieces": {
    "0": {
      "id": 0,
      "size": 4194304,
      "length": 4194304,
      "completed": true,
      "priority": 7
    }
  },
  "readers": [\
    {\
      "start": 10,\
      "end": 50,\
      "reader": 25\
    }\
  ],
  "torrent": { ... }
}
```

**Sources:** [server/torr/storage/torrstor/cache.go139-185](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/storage/torrstor/cache.go#L139-L185) [server/torr/torrent.go388-395](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L388-L395)

#### Torrent Status - GET `/api/torrents/status`

Alias for getting single torrent status.

**Query Parameters:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `hash` | string | Yes | Torrent InfoHash (hex) |

**Response:** Returns `TorrentStatus` object.

**Sources:** [server/torr/torrent.go302-386](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L302-L386)

### Streaming

#### Stream File - GET `/stream/{hash}/{id}`

Streams a specific file from a torrent. Supports HTTP range requests for seeking.

**Path Parameters:**

| Parameter | Description |
| --- | --- |
| `hash` | Torrent InfoHash (hex) |
| `id` | File ID (1-based index from `file_stats`) |

**Query Parameters:**

| Parameter | Type | Description |
| --- | --- | --- |
| `preload` | boolean | Enable preloading (default: false) |
| `stat` | boolean | Return file stats instead of streaming |
| `link` | boolean | Return M3U playlist |

**Headers:**

| Header | Description |
| --- | --- |
| `Range` | Byte range (e.g., `bytes=0-1023`) |

**Response:**

- Content-Type: Based on file extension
- Content-Length: File size or range size
- Accept-Ranges: `bytes`
- Content-Range: Byte range (if Range request)

**Sources:** Referenced in architecture diagrams, implementation in streaming module

#### Play File - GET `/play/{hash}/{id}`

Identical to `/stream/` but with automatic preloading enabled.

**Sources:** Referenced in architecture diagrams

### Settings

#### Get Settings - GET `/api/settings`

Returns current BitTorrent configuration.

**Response (JSON):**

```
{
  "cache_size": 1073741824,
  "preload_cache": 5,
  "reader_read_ahead": 95,
  "use_disk": false,
  "torrents_save_path": "/tmp/torrserver",
  "force_encrypt": false,
  "disable_tcp": false,
  "disable_utp": false,
  "disable_upnp": false,
  "disable_dht": false,
  "disable_pex": false,
  "disable_upload": false,
  "download_rate_limit": 0,
  "upload_rate_limit": 0,
  "connections_limit": 25,
  "dht_connection_limit": 500,
  "peers_list_port": 0,
  "retriackers_mode": 1,
  "torrent_disconnect_timeout": 30,
  "enable_ipv6": false,
  "enable_debug": false,
  "enable_dlna": false,
  "ssl_cert": "",
  "ssl_key": "",
  "remove_cache_on_drop": false
}
```

**Sources:** [server/settings package referenced](https://github.com/YouROK/TorrServer/blob/d266990f/server/settings%20package%20referenced) [server/torr/apihelper.go214-229](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L214-L229)

#### Set Settings - POST `/api/settings`

Updates BitTorrent configuration. Triggers reconnection of torrent client.

**Request Body:** Same structure as GET response

**Response:** HTTP 200 OK

**Side Effects:**

1. All active torrents are dropped
2. BitTorrent client disconnects
3. BitTorrent client reconnects with new settings
4. Database is updated

**Sources:** [server/torr/apihelper.go214-229](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L214-L229)

#### Reset Settings - POST `/api/settings/default`

Resets all settings to defaults.

**Response:** HTTP 200 OK

**Sources:** [server/torr/apihelper.go231-246](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L231-L246)

### Search

#### Search Torrents - GET `/api/search`

Searches for torrents using configured Torznab indexers or local RuTor database.

**Query Parameters:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | Search query |
| `provider` | string | No | Specific provider to use |

**Response (JSON):**

```
[\
  {\
    "title": "Example Movie",\
    "link": "magnet:?xt=...",\
    "size": 1234567890,\
    "seeders": 100,\
    "leechers": 20,\
    "provider": "RuTor"\
  }\
]
```

**Sources:** Referenced in architecture diagrams, RuTor integration

### System

#### Echo - GET `/echo`

Health check endpoint. Returns server version.

**Response (text/plain):**

```
MatriX.137
```

**Sources:** [server/web/server.go139-151](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L139-L151) [server/version/version.go8](https://github.com/YouROK/TorrServer/blob/d266990f/server/version/version.go#L8-L8)

#### Shutdown - GET `/shutdown`

Gracefully shuts down the server.

**Response:** HTTP 200 OK before shutdown

**Side Effects:**

1. Disconnects all torrents
2. Closes database
3. Exits process

**Sources:** [server/torr/apihelper.go255-260](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L255-L260)

#### Viewed - POST `/api/viewed`

Marks torrent files as viewed (updates timestamp).

**Request Body (JSON):**

```
{
  "hash": "abc123...",
  "file_id": 1
}
```

**Sources:** Referenced in API helper module

## Common Response Structures

### TorrentStatus Object

```
{
  "stat": 2,
  "stat_string": "Working",
  "hash": "abc123...",
  "name": "Torrent Name",
  "title": "Display Title",
  "category": "Movies",
  "poster": "https://example.com/poster.jpg",
  "data": "{\"custom\":\"metadata\"}",
  "timestamp": 1704067200,
  "torrent_size": 2345678901,
  "loaded_size": 1234567890,
  "preload_size": 104857600,
  "preloaded_bytes": 52428800,
  "download_speed": 1048576.5,
  "upload_speed": 262144.2,
  "bitrate": "5000 kb/s",
  "duration_seconds": 7200.5,
  "bytes_written": 987654321,
  "bytes_written_data": 987654320,
  "bytes_read": 876543210,
  "bytes_read_data": 876543200,
  "bytes_read_useful_data": 865432100,
  "chunks_written": 12345,
  "chunks_read": 11234,
  "chunks_read_useful": 11000,
  "chunks_read_wasted": 234,
  "pieces_dirtied_good": 1000,
  "pieces_dirtied_bad": 5,
  "total_peers": 45,
  "pending_peers": 10,
  "active_peers": 12,
  "connected_seeders": 8,
  "half_open_peers": 3,
  "file_stats": [\
    {\
      "id": 1,\
      "path": "video.mkv",\
      "length": 2345678901\
    }\
  ],
  "torrs_hash": "eyJoYXNoIjoiYWJjMTIzLi4uIn0="
}
```

**Field Descriptions:**

| Field | Type | Description |
| --- | --- | --- |
| `stat` | integer | State code (0=Added, 1=GettingInfo, 2=Working, 3=Preload, 4=Closed) |
| `stat_string` | string | Human-readable state |
| `hash` | string | InfoHash (hex) |
| `name` | string | Torrent name from metadata |
| `title` | string | User-defined title |
| `torrent_size` | integer | Total torrent size (bytes) |
| `loaded_size` | integer | Downloaded bytes |
| `download_speed` | float | Current download speed (bytes/sec) |
| `upload_speed` | float | Current upload speed (bytes/sec) |
| `active_peers` | integer | Currently connected peers |
| `file_stats` | array | List of files in torrent |
| `torrs_hash` | string | Signed hash token for sharing |

**Sources:** [server/torr/torrent.go302-386](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L302-L386) [server/torr/state package](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/state%20package)

### CacheState Object

```
{
  "capacity": 1073741824,
  "filled": 536870912,
  "pieces_length": 4194304,
  "pieces_count": 256,
  "hash": "abc123...",
  "pieces": {
    "0": {
      "id": 0,
      "size": 4194304,
      "length": 4194304,
      "completed": true,
      "priority": 7
    }
  },
  "readers": [\
    {\
      "start": 10,\
      "end": 50,\
      "reader": 25\
    }\
  ]
}
```

**Field Descriptions:**

| Field | Type | Description |
| --- | --- | --- |
| `capacity` | integer | Maximum cache size (bytes) |
| `filled` | integer | Current cache usage (bytes) |
| `pieces_length` | integer | Size of each piece (bytes) |
| `pieces_count` | integer | Total number of pieces |
| `pieces` | object | Map of piece ID to piece state |
| `readers` | array | Active reader positions and ranges |

**Sources:** [server/torr/storage/torrstor/cache.go139-185](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/storage/torrstor/cache.go#L139-L185)

## Request/Response Flow Diagram

```
CacheTorrentBTServerAPIHandlerMiddlewareGinCache["Cache System"]Torrent["Torrent Object"]BTServer["BTServer"]APIHandler["API Handler"]Middleware["Middleware Stack"]Gin["Gin Router"]ClientCacheTorrentBTServerAPIHandlerMiddlewareGinCache["Cache System"]Torrent["Torrent Object"]BTServer["BTServer"]APIHandler["API Handler"]Middleware["Middleware Stack"]Gin["Gin Router"]ClientPOST /api/torrentsProcess RequestLoggerIP BlockerAuth CheckCORSForwardAddTorrent()NewTorrent()Init CacheCache ReadyTorrent ObjectTorrent ObjectStatus()TorrentStatusJSON Response
```

**Sources:** [server/web/server.go76-78](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L76-L78) [server/torr/apihelper.go40-81](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L40-L81) [server/torr/btserver.go56-71](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/btserver.go#L56-L71) [server/torr/torrent.go60-109](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L60-L109)

## Error Responses

All API endpoints return standard HTTP status codes with JSON error responses.

### Error Response Format

```
{
  "error": "error message",
  "code": 400
}
```

### HTTP Status Codes

| Code | Meaning | Common Scenarios |
| --- | --- | --- |
| 200 | OK | Successful request |
| 400 | Bad Request | Invalid parameters, malformed JSON |
| 401 | Unauthorized | Authentication required but not provided |
| 403 | Forbidden | Valid auth but insufficient permissions |
| 404 | Not Found | Torrent not found, invalid hash |
| 500 | Internal Server Error | Server-side error, torrent client error |

**Sources:** Standard Gin error handling

## Authentication Flow

```

No

Yes

No

Yes

Yes

No

API Request

Has Authorization
Header?

Auth
Required?

Validate Credentials
auth.SetupAuth()

Allow Access

401 Unauthorized

Valid
Credentials?

Route Handler

Error Response
```

**Sources:** [server/web/server.go78](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L78-L78) [server/web/auth package](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/auth%20package)

## API Client Integration Examples

### Python Example

```
import requests

base_url = "http://localhost:8090"

# Add torrent
response = requests.post(f"{base_url}/api/torrents", json={
    "action": "add",
    "link": "magnet:?xt=urn:btih:...",
    "title": "Example Movie"
})
torrent = response.json()
print(f"Added: {torrent['hash']}")

# Get status
status = requests.get(f"{base_url}/api/torrents").json()
print(f"Torrents: {len(status)}")

# Stream file
stream_url = f"{base_url}/stream/{torrent['hash']}/1"
```

### cURL Example

```
# Add torrent
curl -X POST http://localhost:8090/api/torrents \
  -H "Content-Type: application/json" \
  -d '{"action":"add","link":"magnet:?xt=..."}'

# List torrents
curl http://localhost:8090/api/torrents

# Get cache state
curl "http://localhost:8090/api/cache?hash=abc123..."

# Stream file (with range request)
curl -H "Range: bytes=0-1048575" \
  http://localhost:8090/stream/abc123.../1
```

## Swagger Documentation

TorrServer includes interactive Swagger/OpenAPI documentation accessible at:

```
http://localhost:8090/swagger/index.html
```

The Swagger UI provides:

- Interactive API testing
- Request/response schemas
- Authentication configuration
- Example values
- Try-it-out functionality

API documentation is generated from Go code annotations using `swag` tool during build process.

**Sources:** [server/web/server.go96](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L96-L96) [server/go.mod26-28](https://github.com/YouROK/TorrServer/blob/d266990f/server/go.mod#L26-L28)

## API Code Mapping

| Endpoint | Handler Function | Source File |
| --- | --- | --- |
| `POST /api/torrents` | `AddTorrent()` | [server/torr/apihelper.go40-81](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L40-L81) |
| `GET /api/torrents` | `ListTorrent()` | [server/torr/apihelper.go183-207](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L183-L207) |
| `POST /api/set` | `SetTorrent()` | [server/torr/apihelper.go120-159](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L120-L159) |
| `POST /api/drop` | `DropTorrent()` | [server/torr/apihelper.go209-212](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L209-L212) |
| `POST /api/rem` | `RemTorrent()` | [server/torr/apihelper.go161-181](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L161-L181) |
| `GET /api/cache` | `GetCache()` via `CacheState()` | [server/torr/torrent.go388-395](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/torrent.go#L388-L395) |
| `GET /api/settings` | Settings getter | Referenced in apihelper |
| `POST /api/settings` | `SetSettings()` | [server/torr/apihelper.go214-229](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L214-L229) |
| `GET /echo` | `echo()` | [server/web/server.go149-151](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go#L149-L151) |
| `GET /shutdown` | `Shutdown()` | [server/torr/apihelper.go255-260](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go#L255-L260) |

**Sources:** [server/web/api package](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/api%20package) [server/torr/apihelper.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/torr/apihelper.go) [server/web/server.go](https://github.com/YouROK/TorrServer/blob/d266990f/server/web/server.go)

This wiki is featured in the [repository](https://github.com/YouROK/TorrServer/blob/master/README.md)

Dismiss

Refresh this wiki

Enter email to refresh

### On this page

- [REST API Reference](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#rest-api-reference)
- [API Overview](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#api-overview)
- [Base Configuration](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#base-configuration)
- [URL Structure](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#url-structure)
- [Authentication](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#authentication)
- [Middleware Stack](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#middleware-stack)
- [API Endpoint Categories](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#api-endpoint-categories)
- [Endpoint Overview Table](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#endpoint-overview-table)
- [Endpoint Hierarchy Diagram](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#endpoint-hierarchy-diagram)
- [Core API Endpoints](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#core-api-endpoints)
- [Torrent Management](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#torrent-management)
- [Add Torrent - POST \`/api/torrents\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#add-torrent---post-apitorrents)
- [List Torrents - GET \`/api/torrents\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#list-torrents---get-apitorrents)
- [Edit Torrent - POST \`/api/set\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#edit-torrent---post-apiset)
- [Drop Torrent - POST \`/api/drop\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#drop-torrent---post-apidrop)
- [Delete Torrent - POST \`/api/rem\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#delete-torrent---post-apirem)
- [Cache & Status](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#cache-status)
- [Cache State - GET \`/api/cache\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#cache-state---get-apicache)
- [Torrent Status - GET \`/api/torrents/status\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#torrent-status---get-apitorrentsstatus)
- [Streaming](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#streaming)
- [Stream File - GET \`/stream/{hash}/{id}\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#stream-file---get-streamhashid)
- [Play File - GET \`/play/{hash}/{id}\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#play-file---get-playhashid)
- [Settings](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#settings)
- [Get Settings - GET \`/api/settings\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#get-settings---get-apisettings)
- [Set Settings - POST \`/api/settings\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#set-settings---post-apisettings)
- [Reset Settings - POST \`/api/settings/default\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#reset-settings---post-apisettingsdefault)
- [Search](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#search)
- [Search Torrents - GET \`/api/search\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#search-torrents---get-apisearch)
- [System](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#system)
- [Echo - GET \`/echo\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#echo---get-echo)
- [Shutdown - GET \`/shutdown\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#shutdown---get-shutdown)
- [Viewed - POST \`/api/viewed\`](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#viewed---post-apiviewed)
- [Common Response Structures](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#common-response-structures)
- [TorrentStatus Object](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#torrentstatus-object)
- [CacheState Object](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#cachestate-object)
- [Request/Response Flow Diagram](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#requestresponse-flow-diagram)
- [Error Responses](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#error-responses)
- [Error Response Format](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#error-response-format)
- [HTTP Status Codes](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#http-status-codes)
- [Authentication Flow](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#authentication-flow)
- [API Client Integration Examples](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#api-client-integration-examples)
- [Python Example](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#python-example)
- [cURL Example](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#curl-example)
- [Swagger Documentation](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#swagger-documentation)
- [API Code Mapping](https://deepwiki.com/YouROK/TorrServer/3.9-rest-api-reference#api-code-mapping)

Ask Devin about YouROK/TorrServer

Fast