/api/drd/server/post

Parameters

Which parameters apply depends on the role. The RAIDA role describes a detection agent (slot number, jurisdiction, benchmark); the four service roles describe a mailbox, beacon, directory, or key-exchange host (hardware, storage, welfare, subscriptions). Sending a parameter that does not belong to the chosen role is rejected by the RAIDAs (status 198), so send only the rows marked for your role.

Identity and role

Addresses (all roles)

RAIDA role only

Service roles (qmail, beacon, drd, rke)

QMail role only

Responses

Success Response (200)

At least one RAIDA accepted the descriptor. The fan-out fields are shared by every DRD endpoint: pass_count (RAIDAs reporting success), fail_count (responded but did not succeed), no_response_count (no answer), and skipped_count (marked offline by the availability echo, so not attempted). Together they total 25. quorum is true when 13 or more accepted, and raida_results holds one entry per server (truncated below). Because RAIDAs keep independent directories, check quorum rather than success alone; a re-post later will fill in the servers that missed.

{
    "command": "drd-server-post",
    "success": true,
    "role": "raida",
    "denomination": 5,
    "serial_number": 17,
    "raida_id": 11,
    "pass_count": 25,
    "fail_count": 0,
    "no_response_count": 0,
    "skipped_count": 0,
    "quorum": true,
    "raida_results": [
        { "raida": 0, "success": true, "status": 250 },
        { "raida": 1, "success": true, "status": 250 }
    ]
}

Error Responses

400 Bad Request

Missing or unknown role; RAIDA role without raida_id or jurisdiction; raida_id outside 0–24; a numeric parameter that is not a non-negative integer; version that does not fit 32 bits; subscriptions_available=1 without a subscription_url; or a subscription_url that is not https://.

{
    "error": true,
    "message": "Missing or invalid role (raida|qmail|beacon|drd|rke)",
    "code": 400
}

{
    "error": true,
    "message": "RAIDA role requires raida_id (0-24) and jurisdiction",
    "code": 400
}

{
    "error": true,
    "message": "subscription_url required when subscriptions_available=1",
    "code": 400
}

404 Not Found

No identity coin: the server-id wallet is empty, or the override sn was not found in the wallet.

{
    "error": true,
    "message": "No identity coin in the server-id wallet (pass sn/wallet to override)",
    "code": 404
}

500 Internal Server Error

The core could not select an HV=2 encryption coin pair from its wallets, or the fan-out could not be built (typically a parameter that is illegal for the chosen role).

{
    "error": true,
    "message": "No encryption coin pair available for HV=2",
    "code": 500
}

502 Bad Gateway

No RAIDA accepted the registration. The body names the dominant RAIDA status and includes the per-server detail. Common causes: status 198 (a role/parameter mismatch, a slot conflict, or a coin denomination not allowed for the role), status 200 (identity coin AN mismatch — the coin has been powned elsewhere), or status 219 (a RAIDA running software without HV=2 support).

{
    "error": true,
    "message": "No RAIDA accepted the registration",
    "code": 502,
    "raida_status_code": 198,
    "detail": "Invalid parameter",
    "pass_count": 0,
    "fail_count": 25,
    "no_response_count": 0,
    "skipped_count": 0,
    "quorum": false,
    "raida_results": [
        { "raida": 0, "success": false, "status": 198, "error": "Invalid parameter" }
    ]
}

Examples

cURL Example

Register RAIDA slot 11:

curl -X GET "http://localhost:8080/api/drd/server/post?role=raida&raida_id=11&jurisdiction=Iceland&ip4=203.0.113.11&benchmark_ms=42&network_speed_bps=1000000000"

Register the same machine’s QMail service:

curl -X GET "http://localhost:8080/api/drd/server/post?role=qmail&ip4=203.0.113.11&storage_available=2000000000000&max_object=1073741824&welfare_bytes=307200&encryption_types=4,8&version=20260905&subscriptions_available=1&subscription_url=https://mail.example.com/subscribe"

JavaScript Example

const params = new URLSearchParams({
    role: 'qmail',
    ip4: '203.0.113.11',
    storage_available: '2000000000000',
    welfare_bytes: '307200',
    encryption_types: '4,8',
    version: '20260905'
});

fetch(`http://localhost:8080/api/drd/server/post?${params}`)
    .then(r => r.json())
    .then(data => {
        if (data.success) {
            console.log(`Registered ${data.role} as DN${data.denomination}.${data.serial_number}: ` +
                        `${data.pass_count}/25 RAIDAs, quorum=${data.quorum}`);
        } else {
            console.error(data.message, data.detail || '');
        }
    });

Python Example

import requests

url = 'http://localhost:8080/api/drd/server/post'
params = {
    'role': 'raida',
    'raida_id': 11,
    'jurisdiction': 'Iceland',
    'ip4': '203.0.113.11',
    'benchmark_ms': 42,
}
data = requests.get(url, params=params).json()

if data.get('success'):
    print(f"slot {data['raida_id']} registered on {data['pass_count']}/25 RAIDAs "
          f"(quorum={data['quorum']})")
    for r in data['raida_results']:
        if not r['success']:
            print(f"  RAIDA {r['raida']}: status {r['status']} {r.get('error', '')}")
else:
    print('Error', data.get('code'), data.get('message'), data.get('detail', ''))

Notes

• Identity coin. By default the request is signed with the first note in the server-id wallet — the machine’s identity note. Every RAIDA authenticates that coin’s AN exactly as detect does. Keep that wallet backed up: the slot-to-coin binding for the RAIDA role cannot be transferred to a new coin without a manual admin edit on every RAIDA.
• Timestamps are server-stamped. Each RAIDA sets created_at on first insert, bumps updated_at only when a fact actually changed, and bumps last_seen_at on every successful post. Re-posting on a timer (hourly is the planned default) is what keeps a server looking alive in the directory.
• The directory is advisory. Being listed does not grant admission anywhere; each service still makes its own admission decision (for QMail, the object-transfer begin command). The directory is how clients discover servers, not how servers gain trust.
• is_a_raida is computed by the RAIDAs, never accepted from the caller: a qmail/beacon/drd/rke row is marked as belonging to a RAIDA only when the same 100,000 CC coin also holds a RAIDA slot.
• This endpoint requires every RAIDA to run software with HV=2 support for group 16. Older RAIDAs answer status 219 and count as failures.

Related Endpoints

• /api/drd/server/get - Read registered server descriptors
• /api/drd/user/post - Register a user (not a server) in the directory
• Protocol: 149 server_post - Wire format the core sends to each RAIDA