Skip to content

API.md

Latest commit

 

History

History
533 lines (441 loc) · 9.79 KB

API.md

File metadata and controls

533 lines (441 loc) · 9.79 KB

Irys Server API Documentation

Base URL: http://localhost:7711/api

Authentication

All endpoints except health check and registration require authentication via JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Response Format

All API responses follow this format:

{
  "success": true|false,
  "message": "Human readable message",
  "data": { ... },
  "error": "Error message (if success is false)"
}

Endpoints

Health Check

GET /health

Check server health status.

Response:

{
  "status": "healthy",
  "timestamp": "2023-12-01T10:00:00.000Z",
  "uptime": 3600,
  "environment": "development"
}

Authentication Endpoints

Register User

POST /api/auth/register

Register a new user account.

Request Body:

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecurePassword123!"
}

Response:

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "user": {
      "id": "johndoe",
      "username": "johndoe",
      "email": "john@example.com",
      "publicKey": "-----BEGIN PUBLIC KEY-----...",
      "createdAt": "2023-12-01T10:00:00.000Z"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Login

POST /api/auth/login

Authenticate user and get access token.

Request Body:

{
  "username": "johndoe",
  "password": "SecurePassword123!"
}

Response:

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "johndoe",
      "username": "johndoe",
      "email": "john@example.com",
      "publicKey": "-----BEGIN PUBLIC KEY-----...",
      "groups": ["group1", "group2"]
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Get Profile

GET /api/auth/profile

Get current user profile information.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "johndoe",
      "username": "johndoe",
      "email": "john@example.com",
      "publicKey": "-----BEGIN PUBLIC KEY-----...",
      "createdAt": "2023-12-01T10:00:00.000Z",
      "groups": [
        {
          "id": "group1",
          "name": "Research Team",
          "role": "admin"
        }
      ]
    }
  }
}

Get Public Key

GET /api/auth/public-key/:username

Get public key for a specific user.

Response:

{
  "success": true,
  "data": {
    "username": "johndoe",
    "publicKey": "-----BEGIN PUBLIC KEY-----..."
  }
}

File Management Endpoints

Upload File

POST /api/files/upload

Upload a file to Irys with optional encryption.

Headers:

  • Authorization: Bearer <token>
  • Content-Type: multipart/form-data

Form Data:

  • file: File to upload (required)
  • fileName: Custom file name (optional)
  • description: File description (optional)
  • isPrivate: "true" or "false" (default: false)
  • groupId: Group ID for group files (optional)
  • tags: JSON array of tags (optional)

Response:

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "txId": "abc123...",
    "fileName": "document.pdf",
    "size": 1024000,
    "contentType": "application/pdf",
    "isPrivate": false,
    "groupId": null,
    "irysUrl": "https://gateway.irys.xyz/abc123...",
    "uploadedAt": "2023-12-01T10:00:00.000Z"
  }
}

Download File

GET /api/files/download/:txId

Download a file by transaction ID.

Headers: Authorization: Bearer <token>

Response: File content with appropriate headers

Get File Metadata

GET /api/files/metadata/:txId

Get metadata for a specific file.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "txId": "abc123...",
    "fileName": "document.pdf",
    "originalName": "original-document.pdf",
    "contentType": "application/pdf",
    "size": 1024000,
    "description": "Important document",
    "isPrivate": false,
    "groupId": null,
    "tags": ["document", "important"],
    "uploadedBy": "johndoe",
    "uploadedAt": "2023-12-01T10:00:00.000Z",
    "irysUrl": "https://gateway.irys.xyz/abc123..."
  }
}

List User Files

GET /api/files/my

List files accessible to the current user.

Headers: Authorization: Bearer <token>

Query Parameters:

  • limit: Number of files to return (default: 20)
  • offset: Number of files to skip (default: 0)
  • groupId: Filter by group ID
  • isPrivate: Filter by privacy ("true" or "false")

Response:

{
  "success": true,
  "data": {
    "files": [
      {
        "txId": "abc123...",
        "fileName": "document.pdf",
        "contentType": "application/pdf",
        "size": 1024000,
        "description": "Important document",
        "isPrivate": false,
        "groupId": null,
        "tags": ["document"],
        "uploadedBy": "johndoe",
        "uploadedAt": "2023-12-01T10:00:00.000Z"
      }
    ],
    "pagination": {
      "total": 50,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  }
}

Delete File

DELETE /api/files/:txId

Delete a file (removes metadata reference).

Headers: Authorization: Bearer <token>

Response:

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

Group Management Endpoints

Create Group

POST /api/groups

Create a new group.

Headers: Authorization: Bearer <token>

Request Body:

{
  "name": "Research Team",
  "description": "Collaborative research group",
  "isPrivate": false,
  "tags": ["research", "collaboration"]
}

Response:

{
  "success": true,
  "message": "Group created successfully",
  "data": {
    "group": {
      "id": "group_123",
      "name": "Research Team",
      "description": "Collaborative research group",
      "isPrivate": false,
      "publicKey": "-----BEGIN PUBLIC KEY-----...",
      "createdBy": "johndoe",
      "createdAt": "2023-12-01T10:00:00.000Z",
      "members": ["johndoe"],
      "admins": ["johndoe"]
    }
  }
}

List Public Groups

GET /api/groups/public

List all public groups.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "group_123",
        "name": "Research Team",
        "description": "Collaborative research group",
        "publicKey": "-----BEGIN PUBLIC KEY-----...",
        "createdBy": "johndoe",
        "createdAt": "2023-12-01T10:00:00.000Z",
        "memberCount": 5
      }
    ]
  }
}

List User Groups

GET /api/groups/my

List groups the current user belongs to.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "group_123",
        "name": "Research Team",
        "description": "Collaborative research group",
        "isPrivate": false,
        "publicKey": "-----BEGIN PUBLIC KEY-----...",
        "createdBy": "johndoe",
        "createdAt": "2023-12-01T10:00:00.000Z",
        "memberCount": 5,
        "role": "admin"
      }
    ]
  }
}

Join Group

POST /api/groups/:groupId/join

Join a public group.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "message": "Successfully joined group",
  "data": {
    "groupId": "group_123",
    "role": "member"
  }
}

Search Endpoints

Basic Search

GET /api/search

Search for files with basic filters.

Headers: Authorization: Bearer <token>

Query Parameters:

  • query: Search term
  • tags: Array of tags to filter by
  • contentType: Filter by content type
  • isPrivate: Filter by privacy
  • groupId: Filter by group
  • limit: Results limit (default: 20)
  • offset: Results offset (default: 0)
  • sortBy: Sort field (createdAt, fileName, size)
  • sortOrder: Sort order (asc, desc)

Response:

{
  "success": true,
  "data": {
    "files": [
      {
        "txId": "abc123...",
        "fileName": "research-paper.pdf",
        "contentType": "application/pdf",
        "size": 2048000,
        "description": "Machine learning research",
        "isPrivate": false,
        "groupId": "group_123",
        "tags": ["research", "ml"],
        "uploadedBy": "johndoe",
        "uploadedAt": "2023-12-01T10:00:00.000Z",
        "relevanceScore": 15
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    },
    "filters": {
      "query": "machine learning",
      "tags": ["research"],
      "contentType": null,
      "isPrivate": null,
      "groupId": null
    }
  }
}

Search Suggestions

GET /api/search/suggestions

Get search suggestions based on query.

Headers: Authorization: Bearer <token>

Query Parameters:

  • q: Partial search term (minimum 2 characters)

Response:

{
  "success": true,
  "data": {
    "suggestions": [
      "machine learning",
      "machine vision",
      "javascript tutorial"
    ]
  }
}

Popular Tags

GET /api/search/tags

Get popular tags from accessible files.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "tags": [
      {
        "tag": "research",
        "count": 15
      },
      {
        "tag": "programming",
        "count": 12
      }
    ]
  }
}

Error Codes

Code Description
400 Bad Request - Invalid input data
401 Unauthorized - Missing or invalid token
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Resource already exists
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Rate Limiting

  • Default: 100 requests per 15 minutes per IP
  • Configurable via environment variables
  • Returns 429 status when exceeded