Skip to content

API Reference

FuryMesh provides a comprehensive REST API that allows you to integrate with and control FuryMesh programmatically. This reference documents all available endpoints, request parameters, and response formats.

API Overview

The FuryMesh API is available when you start FuryMesh with the --enable-api flag:

furymesh start --enable-api --api-port 8081

By default, the API listens on http://localhost:8081. All API endpoints return JSON responses.

Authentication

API requests can be authenticated using an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8081/api/v1/files

To generate an API key:

furymesh generate-api-key

Endpoints

Node Management

GET /api/v1/node/info

Returns information about the current node.

Response:

{
  "node_id": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
  "version": "1.0.0",
  "uptime": 3600,
  "peers_connected": 5,
  "storage_used": 1024000,
  "storage_available": 10240000000
}

GET /api/v1/node/peers

Lists all connected peers.

Response:

{
  "peers": [
    {
      "id": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
      "address": "203.0.113.1:8080",
      "connected_since": "2023-01-01T12:00:00Z",
      "files_available": 10
    },
    {
      "id": "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V",
      "address": "203.0.113.2:8080",
      "connected_since": "2023-01-01T12:30:00Z",
      "files_available": 5
    }
  ]
}

File Management

GET /api/v1/files

Lists all files available locally.

Response:

{
  "files": [
    {
      "id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
      "name": "example.txt",
      "size": 1024,
      "chunks": 2,
      "created_at": "2023-01-01T12:00:00Z",
      "complete": true
    }
  ]
}

POST /api/v1/files/share

Shares a file on the network.

Request:

{
  "file_path": "/path/to/file.txt"
}

Response:

{
  "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
  "name": "file.txt",
  "size": 1024,
  "chunks": 2
}

GET /api/v1/files/network

Lists all files available on the network.

Response:

{
  "files": [
    {
      "id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
      "name": "example.txt",
      "size": 1024,
      "peers": ["QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG"]
    }
  ]
}

DELETE /api/v1/files/{file_id}

Deletes a file from local storage.

Response:

{
  "success": true,
  "message": "File deleted successfully"
}

Transfer Management

POST /api/v1/transfers/download

Starts downloading a file.

Request:

{
  "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
  "output_path": "/path/to/save/file.txt",
  "multi_peer": true
}

Response:

{
  "transfer_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
  "status": "started"
}

GET /api/v1/transfers

Lists all active transfers.

Response:

{
  "transfers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
      "status": "in_progress",
      "progress": 0.5,
      "speed": 1048576,
      "peers": 2,
      "started_at": "2023-01-01T12:00:00Z"
    }
  ]
}

GET /api/v1/transfers/{transfer_id}

Gets information about a specific transfer.

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
  "status": "in_progress",
  "progress": 0.5,
  "speed": 1048576,
  "peers": [
    {
      "id": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG",
      "chunks_downloaded": 1,
      "speed": 524288
    },
    {
      "id": "QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V",
      "chunks_downloaded": 0,
      "speed": 524288
    }
  ],
  "started_at": "2023-01-01T12:00:00Z",
  "estimated_completion": "2023-01-01T12:01:00Z"
}

POST /api/v1/transfers/{transfer_id}/cancel

Cancels an active transfer.

Response:

{
  "success": true,
  "message": "Transfer cancelled"
}

POST /api/v1/transfers/resume/{file_id}

Resumes a previously interrupted transfer.

Response:

{
  "transfer_id": "550e8400-e29b-41d4-a716-446655440000",
  "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
  "status": "resumed",
  "progress": 0.5
}

System Management

GET /api/v1/system/stats

Returns system statistics.

Response:

{
  "cpu_usage": 0.2,
  "memory_usage": 104857600,
  "disk_usage": 1073741824,
  "network": {
    "upload_speed": 1048576,
    "download_speed": 2097152,
    "total_uploaded": 10485760,
    "total_downloaded": 20971520
  }
}

Error Handling

All API errors follow a standard format:

{
  "error": true,
  "code": 404,
  "message": "File not found"
}

Common error codes:

  • 400: Bad Request - The request was malformed
  • 401: Unauthorized - Authentication is required
  • 403: Forbidden - The request is not allowed
  • 404: Not Found - The requested resource does not exist
  • 500: Internal Server Error - Something went wrong on the server

Rate Limiting

API requests are rate-limited to 100 requests per minute per IP address. When the rate limit is exceeded, the API returns a 429 Too Many Requests response.

Webhooks

FuryMesh can send webhook notifications for various events. Configure webhooks using:

furymesh start --webhook-url "https://example.com/webhook" --webhook-events "transfer_complete,peer_connected"

Webhook payloads follow this format:

{
  "event": "transfer_complete",
  "timestamp": "2023-01-01T12:00:00Z",
  "data": {
    "file_id": "QmZ4tDuvesekSs4qM5ZBKpXiZGun7S2CYtEZRB3DYXkjGx",
    "size": 1024,
    "duration": 60
  }
}

Client Libraries

FuryMesh provides official client libraries for easy integration: