# Janus Server API

The Janus server provides HTTP endpoints for accepting transaction bundles and scry bindings. The Janus server runs in-process for galaxy validators and as part of zenithd in star mode. Endpoints are available based on the node's operational mode.

## Galaxy Endpoints

Galaxy endpoints are only available when zenithd is running in galaxy mode. These endpoints accept protobuf-encoded data.

### Submit Transaction Bundle

```bash
# Submit a protobuf-encoded bundle from a star
# The bundle includes star ID, transactions, and star signature
curl -X POST http://localhost:8080/api/galaxy/submit/bundle \
  -H "Content-Type: application/octet-stream" \
  --data-binary @bundle.pb
```

**Response:**

```json
{
  "success": true,
  "message": "Bundle processed successfully",
  "bundle_id": "bundle-uuid"
}
```

### Submit Scry Binding Batch

```bash
# Submit a protobuf-encoded scry batch from a star
# Includes star ID, scry bindings with individual signatures
curl -X POST http://localhost:8080/api/galaxy/submit/scry \
  -H "Content-Type: application/octet-stream" \
  --data-binary @scry_batch.pb
```

**Response:**

```json
{
  "success": true,
  "message": "Scry bindings processed successfully",
  "star_id": "12345",
  "bindings_processed": 10
}
```

### Queue Status

```bash
# Get current bundle queue status (galaxy mode only)
curl http://localhost:8080/api/galaxy/queue/status
```

**Response:**

```json
{
  "pending_bundles": 5,
  "size_mb": 2.3,
  "max_size_mb": 100
}
```

### Galaxy Health Check

```bash
# Check galaxy Janus server health
curl http://localhost:8080/api/galaxy/health
```

**Response:**

```json
{
  "status": "healthy",
  "server": "janus",
  "node_mode": "galaxy"
}
```

## Star Endpoints

Star endpoints are available when zenithd is running in star or galaxy mode. These endpoints accept transactions and scry bindings from planets.

### Submit Transaction

```bash
# Submit a protobuf-encoded transaction from a planet
curl -X POST http://localhost:8080/api/star/submit/tx \
  -H "Content-Type: application/octet-stream" \
  --data-binary @transaction.pb
```

**Response:**

```json
{
  "success": true,
  "message": "Transaction queued for bundling"
}
```

### Submit Scry Binding

```bash
# Submit a scry binding with Ed25519 signature
curl -X POST http://localhost:8080/api/star/submit/scry \
  -H "Content-Type: application/json" \
  -d '{
    "scry-binding": {
      "path": "/~sampel-palnet/app/data",
      "hash": "0xabc123...",
      "signature": "0xdef456...",
      "life": 1
    }
  }'
```

**Response:**

```json
{
  "success": true,
  "message": "Scry binding queued for submission"
}
```

### Star Status

```bash
# Get star node operational status
curl http://localhost:8080/api/star/status
```

**Response:**

```json
{
  "success": true,
  "data": {
    "node_type": "star",
    "star_id": 12345,
    "timestamp": "2024-01-01T00:00:00Z",
    "pending_transactions": 5,
    "pending_scry_bindings": 3,
    "galaxy_url": "https://galaxy.example.com",
    "max_tx_per_bundle": 100,
    "bundle_timeout": "30s",
    "scry_batch_size": 50,
    "scry_batch_timeout": "60s",
    "require_signatures": true
  }
}
```

### Star Health Check

```bash
# Check star Janus server health
curl http://localhost:8080/api/star/health
```

**Response:**

```json
{
  "status": "healthy",
  "server": "janus",
  "node_mode": "star",
  "zenith_key_loaded": true
}
```

!!! note "Janus Configuration"
    The Janus server configuration (port, endpoints, etc.) is managed through the zenithd configuration file. See the [Janus documentation](../documentation/janus.md) for more details on the transaction aggregation architecture.

!!! warning "Mode Restrictions"
    - Galaxy endpoints (`/api/galaxy/*`) only work in galaxy mode
    - Star endpoints (`/api/star/*`) work in both star and galaxy modes
    - Attempting to access galaxy endpoints in star mode returns a 403 Forbidden error