API Reference

Complete endpoint documentation for the LoomAPI.

API Overview

LoomAPI is a RESTful API that follows standard HTTP conventions. All requests and responses use JSON format. The API is organized into three main areas: verification endpoints (start, complete, status), token endpoints (validate), and admin endpoints (tenant management, metrics).

Verification flow: First, start a verification session with POST /verify/startto receive a verification ID. Next, complete the verification with POST /verify/complete(which returns a JWT token if approved). Finally, validate tokens on subsequent requests with POST /tokens/validateto check if a user is verified and over 18.

Authentication model: Tenant endpoints require API key authentication via the x-tenant-api-key header. Each tenant has isolated rate limits, quotas, and billing. Admin endpoints require a separate x-admin-key header and are used for system management only.

Base URL

https://project-halo-api.onrender.com

Endpoints

Path	Method	Auth Header	Description	Response Fields
/verify/start	POST	x-tenant-api-key	Start a verification session	verificationId, status, sessionUrl (if Veriff enabled), config
/verify/complete	POST	x-tenant-api-key	Submit result & mint token	verificationId, status, confidence, token (if approved)
/verify/status	GET	x-tenant-api-key	Check status by verificationId	verificationId, status, confidence, createdAt, completedAt
/verify/submit	POST	x-tenant-api-key	Submit verification result (approved or rejected)	verificationId, status, completedAt
/tokens/validate	POST	x-tenant-api-key	Validate JWT token	valid, over18, reason
/admin/metrics	GET	x-admin-key	Admin metrics (requires admin key)	uptimeSeconds, dbStatus, redisStatus, totalTenants, totalVerifications
/admin/tenants	GET	x-admin-key	List all tenants (admin only)	Array of tenant objects with id, name, isActive, billing info
/admin/tenants	POST	x-admin-key	Create a new tenant (admin only)	id, name, apiKey, isActive
/admin/tenants/:id	GET	x-admin-key	Get single tenant by ID with stats (admin only)	id, name, apiKey, isActive, totalVerifications, lastVerifications, billing
/admin/logs	GET	x-admin-key	Get recent logs with optional filtering (admin only)	logs (array of log entries with id, time, method, url, status, durationMs, tenantId, event)
/health	GET	none	Health check endpoint	status (ok/degraded), database (connected/disconnected), redis (connected/disconnected)

Try It Now

Example request and response for starting a verification. These are static examples—live API calls will be available soon.

Method & URL

bash

POST https://project-halo-api.onrender.com/verify/start

Headers

json

{
  "Content-Type": "application/json",
  "x-tenant-api-key": "your-api-key-here"
}

Body

json

{
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "ip": "203.0.113.42"
}

Note: This is a static example. Live API testing with a demo tenant will be available in a future update.

Try It Now

Example request and response for validating a token. These are static examples—live API calls will be available soon.

Method & URL

bash

POST https://project-halo-api.onrender.com/tokens/validate

Headers

json

{
  "Content-Type": "application/json",
  "x-tenant-api-key": "your-api-key-here"
}

Body

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Note: This is a static example. Live API testing with a demo tenant will be available in a future update.

Authentication

Most endpoints require authentication via the x-tenant-api-key header. Admin endpoints require the x-admin-key header.

Rate limits: 60 requests per minute per tenant by default. Quota limits are enforced monthly.

Error Codes

All error responses follow a standard format with an error code, optional message, and request ID for tracking.

Authentication Errors

UNAUTHENTICATED_TENANT(401)

Missing or invalid tenant API key, or tenant is inactive

UNAUTHENTICATED_ADMIN(401)

Missing or invalid admin API key

Validation Errors

INVALID_REQUEST_BODY(400)

Request body validation failed

INVALID_PARAMETERS(400)

Invalid query or route parameters

Verification Errors

VERIFICATION_NOT_FOUND(404)

Verification ID not found or doesn't belong to tenant

VERIFICATION_ALREADY_COMPLETED(400)

Verification has already been completed

Token Errors

TOKEN_NOT_FOUND(200)

Token is invalid or doesn't exist (returns valid: false)

TOKEN_EXPIRED(200)

Token has expired (returns valid: false)

TOKEN_INVALID(200)

Token is invalid for other reasons (returns valid: false)

TENANT_MISMATCH(200)

Token belongs to a different tenant (returns valid: false)

Rate Limiting & Quota Errors

RATE_LIMIT_EXCEEDED(429)

Rate limit exceeded for tenant (includes retryAfterSeconds)

QUOTA_EXCEEDED(429)

Monthly quota exceeded

HARD_LIMIT_EXCEEDED(429)

Hard limit exceeded (absolute maximum)

Internal Errors

INTERNAL_ERROR(500)

Unexpected server error (retry with requestId)

DATABASE_ERROR(500)

Database operation failed

REDIS_ERROR(503)

Redis/cache service unavailable

SERVICE_UNAVAILABLE(503)

Service temporarily unavailable

Error Response Format: All errors include an error code, optional message, and requestId for tracking. Include the requestId when contacting support.