REST v1 API Documentation

Overview

ARC-OS provides a RESTful API v1 for programmatic access. The API is tenant-aware, RBAC-protected, and uses API keys for authentication.

Base URL

https://api.arcnat.com/api/v1

Authentication

All requests must include a Bearer token in the Authorization header:

Authorization: Bearer <token>

Additionally, IP allowlisting may be configured per tenant/session.

Health & Readiness

Platform health endpoints (no version prefix; no auth required for liveness/readiness):

GET /api/health – General health (DB, optional Redis, outbox). Returns 200 with status: "ok" or 503 when not ready.
GET /api/health/ready – Readiness probe (DB required; Redis checked when REDIS_URL set). Returns 200 when ready to accept traffic, 503 when not.
GET /api/health/live – Liveness probe. Returns 200 when the process is alive.
GET /api/health/workers – Worker/scheduler health (scheduled jobs status). Returns 200 with worker status; may include not_configured when workers are disabled.

Use /api/health/ready for Kubernetes/orchestrator readiness and /api/health/live for liveness.

Agent Discovery (ANP)

Canonical agent discovery via ANP (Agent Network Protocol). Single source of truth: GET /api/v1/agents/anp/discover. Convenience route GET /api/v1/agents/discover delegates to it.

GET /api/v1/agents/anp/discover – Discover agents by capability. Query: capability (required), status (optional: online | offline | busy). Requires auth; returns 401/403 when unauthenticated, 400 when capability missing or invalid. Response: { success, capability, agents: [{ agentId, capabilities, status, metadata, lastSeen }], count }.
GET /api/v1/agents/discover – Same as above; delegates to ANP discover. Same query params and response.

Implementation: lib/interoperability/mcp-standards.ts (interoperabilityManager.anp); routes: app/api/v1/agents/anp/discover/route.ts (canonical), app/api/v1/agents/discover/route.ts (re-export).

Multi-Agent & MCP Interoperability (A2A, ANP, AG-UI, AGORA, Eclipse LMOS, AP2, Open Agentic Schema)

Single source of truth: lib/interoperability/mcp-standards.ts (InteroperabilityManager). All routes require auth unless noted.

|----------|--------|------|--------|

| ANP | GET | /api/v1/agents/discover | Same; delegates to ANP discover. |

Agent runtime (server/agents/runtime.ts) registers all agents with ANP and A2A handlers; hierarchical coordinator and AI assistant use AGORA for natural-language orchestration. RAG/KAG pipelines use lib/rag and lib/kag; DB tables rag_documents (pgvector) and graph_edges must exist (migrations applied).

Endpoints

Plans

List Plans

GET /api/v1/plans

Response:

{
  "plans": [
    {
      "id": "plan-id",
      "name": "Plan Name",
      "planType": "401k",
      "ein": "12-3456789"
    }
  ]
}

Get Plan

GET /api/v1/plans/:id

Create Plan

POST /api/v1/plans
Content-Type: application/json

{
  "name": "New Plan",
  "planType": "401k",
  "clientId": "client-id"
}

User dashboard

GET /api/v1/user/dashboard-context – User context for routing (entitlements, tenant).
GET /api/v1/user/dashboard/recommendation – AI-powered dashboard recommendation.
GET /api/v1/user/dashboard/available – Available dashboards for the current user.
GET /api/v1/user/dashboard/usage – Dashboard usage analytics (visits, time spent). Returns { success: true, usage: [] }; usage can be extended from analytics/DB.

Analytics

GET /api/v1/analytics/track – Capability check; returns 200 with { ok: true, track: "POST" } so clients do not 404 on GET.
POST /api/v1/analytics/track – Track analytics events. Body: { eventType: string, action?: string, properties?: object }. Requires auth; returns { success: true } or 400 for invalid JSON/missing eventType.

Upload/Download

Upload File

POST /api/v1/upload
Content-Type: multipart/form-data

file: <file>

Response:

{
  "fileId": "file-id",
  "url": "https://...",
  "key": "tenants/tenant-id/files/..."
}

Download File

GET /api/v1/download/:id

Returns presigned URL or file stream.

Evidence

List Evidence Bundles

GET /api/v1/evidence/bundles?planCycleId=cycle-id&bundleType=PlanYear&isSealed=true

Get Evidence Bundle

GET /api/v1/evidence/bundles/:id

Create Evidence Bundle

POST /api/v1/evidence/bundles
Content-Type: application/json

{
  "bundleType": "PlanYear",
  "planCycleId": "cycle-id",
  "references": [...],
  "ruleVersions": [...],
  "eventTrail": [...]
}

Seal Evidence Bundle

POST /api/v1/evidence/bundles/:id/seal
Content-Type: application/json

{
  "immutabilityLevel": "sealed",
  "kmsKeyId": "optional-key-id"
}

Payroll

Dashboard payroll (sources, runs, summary, create source, agent-triggered sync):

GET /api/v1/dashboard/payroll – List payroll sources, runs, plan picklist, and summary (totalSources, totalRuns, runsCompleted, runsFailed, runsPending, recentRunsCount, contributionBatchesCount). Requires auth; returns 401/403 when unauthenticated.
POST /api/v1/dashboard/payroll – Create a payroll source. Body: { planId, name, sourceType: "manual"|"sftp"|"api"|"email", connectionConfig? }. Requires auth.
POST /api/v1/dashboard/payroll/sync – Trigger payroll ingestion via payroll-processing agent. Body: { sourceId, payPeriodStart, payPeriodEnd } (YYYY-MM-DD). Returns { success, runId, status }. Requires auth; 404 if source not found; 502 if agent does not return a run.

Integration payroll sync (gateway, providers, webhooks):

POST /api/v1/payroll/sync – Sync payroll from external provider. Body: { sourceId, provider?, payPeriodStart?, payPeriodEnd?, payrollData?, webhookUrl?, config? }. Uses payroll gateway; supports provider config, webhooks, outbox events. Requires auth; 400 if source inactive or config invalid.

Workflows

Replay Workflow

POST /api/v1/workflows/replay
Content-Type: application/json

{
  "correlationId": "correlation-id",
  "sandbox": true
}

Note: Requires admin permission.

Text-to-Speech (TTS)

TTS is tuned for professional, human-like voice (non-robotic). The client can auto-prefer server TTS when available via GET /api/v1/tts/status.

TTS Status

Returns whether server neural TTS is available (human-like voice). Used by the client to auto-enable server TTS when configured.

GET /api/v1/tts/status
Authorization: Bearer <token>

Response: 200 with { "available": true } when OPENAI_API_KEY is set, else { "available": false }. 401 when unauthenticated.

Synthesize Speech

Generates human-quality speech from text using server-side neural TTS when configured (OpenAI). Requires authentication. When OPENAI_API_KEY is not set, the route returns 503 TTS not configured. Defaults are tuned for natural, professional delivery (non-robotic).

POST /api/v1/tts/synthesize
Content-Type: application/json
Authorization: Bearer <token>

{
  "text": "Text to speak (1–4096 chars)",
  "voice": "shimmer",
  "model": "tts-1-hd",
  "speed": 0.88
}

text (required): 1–4096 characters. Markdown/code is stripped server-side.
voice (optional): alloy | ash | ballad | coral | echo | fable | onyx | nova | sage | shimmer | verse | marin | cedar. Default shimmer (warm, human-like).
model (optional): tts-1 | tts-1-hd | gpt-4o-mini-tts | gpt-4o-mini-tts-2025-12-15. Default tts-1-hd.
speed (optional): 0.25–4. Default 0.88 for natural, conversational pacing (non-robotic).

Response: 200 with body audio/mpeg, or 401 / 503 (not configured) / 429 (provider rate limit) / 400 (validation) / 502 (provider error).

Rate Limiting

Standard API keys: 1000 requests/hour
Business tier: 10000 requests/hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1234567890

IP Management API

The system includes adaptive IP management with risk-based rate limiting:

Endpoints:

GET /api/admin/ip-management?ip= - Get IP statistics and recent events
GET /api/admin/ip-management?all=true&limit=100&orderBy=riskScore - List all tracked IPs
POST /api/admin/ip-management - Whitelist IP or clear IP data

Features:

Adaptive limits based on risk scores (0.5x to 2x base limit)
Auto-whitelisting for trusted IPs
Auto-recovery with grace periods
Complete audit trail in database
Dashboard at /admin/ip-management

Error Responses

All API routes use the canonical error handler (lib/api/error-handler.ts): handleApiError in catch blocks or withErrorHandling wrapper. This ensures consistent status codes, sanitized messages (no stack traces in production), correlation IDs, logging, and metrics. Throw ApiErrorResponse for known client/server errors; other errors are classified and mapped to status codes.

Standard HTTP status codes:

200 - Success
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Rate Limit Exceeded
500 - Internal Server Error

Error response format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {},
  "correlationId": "uuid"
}

Pagination

List endpoints support pagination:

GET /v1/plans?limit=50&offset=0

Response includes:

{
  "data": [...],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 150,
    "hasMore": true
  }
}

Versioning

API version is specified in the URL path (/api/v1/). Future versions will use /api/v2/, etc. Version can also be negotiated via the Accept header (application/vnd.arcos.v1+json) or the version query parameter. All v1 routes that use the canonical route handler (lib/api/route-wrapper.ts) receive version negotiation and response headers (API-Version, API-Latest-Version, and deprecation headers when applicable); logic lives in lib/api/versioning.ts.