REST API

Base URL: https://api.hostswarm.io

Authentication

All endpoints (except /health) require Ed25519 signature authentication. See Authentication for details.

Health

GET /health

Check API health status. No authentication required.

curl https://api.hostswarm.io/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00Z"
}

Registration

POST /v1/auth/register

curl -X POST https://api.hostswarm.io/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "code": "TRIAL-ABC123",
    "public_key": "7a3b9c4d5e6f..."
  }'

Response:

{
  "client_id": "abc123def456",
  "credits": 5000,
  "subdomain": "yourorg.hostswarm.eth"
}

Billing

GET /v1/billing/balance

Get current credit balance.

{
  "credits": 4850,
  "scans_remaining": 485,
  "usd_value": "48.50"
}

Jobs

GET /v1/jobs

List recent analysis jobs.

Query Parameters:

limit Number of jobs (default: 10, max: 100)

{
  "jobs": [
    {
      "job_id": "job_abc123",
      "status": "completed",
      "type": "spine_analysis",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:05Z",
      "credits_used": 10
    }
  ]
}

GET /v1/jobs/{job_id}

Get details of a specific job.

{
  "job_id": "job_abc123",
  "status": "completed",
  "type": "spine_analysis",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z",
  "inference_time_ms": 4720,
  "credits_used": 10,
  "result": {
    "pdf_url": "/v1/jobs/job_abc123/report.pdf",
    "severe_count": 2,
    "moderate_count": 3
  }
}

Error Responses

Code	Description
400	Bad request - Invalid parameters
401	Unauthorized - Invalid or missing signature
402	Payment required - Insufficient credits
404	Not found - Resource doesn't exist
422	Unprocessable - Invalid file format
429	Too many requests - Rate limited
500	Internal server error

Error response format:

{
  "error": "insufficient_credits",
  "message": "You need 10 credits but only have 5",
  "code": 402
}