API Endpoints

Arcturus-Prime exposes 130+ API endpoints as Cloudflare Pages Functions (Workers). Every file in src/pages/api/ becomes a serverless endpoint. This is the complete route inventory, organized by domain with HTTP methods, authentication requirements, and descriptions.

Auth Endpoints (2)

Authentication and role management.

Method	Endpoint	Auth	Description
`GET`	`/api/auth/me`	No	Returns the current user’s identity and role. Returns `null` for unauthenticated requests. Used by the frontend to check login state.
`GET` `POST` `PUT` `DELETE`	`/api/auth/roles`	Admin	Full CRUD for the user roles database in KV. GET lists all roles, POST creates a user, PUT updates a user, DELETE removes a user.

The /api/auth/me endpoint is intentionally public — it returns the current user if authenticated or { user: null } if not. This allows the frontend to conditionally show login/logout UI without a redirect.

The /api/auth/roles endpoint is the admin interface for the data:user-roles KV key. It handles the entire user management workflow:

// GET /api/auth/roles -- List all users and roles
// POST /api/auth/roles -- Create a new user
//   Body: { email, role, displayName, services, features, sites }
// PUT /api/auth/roles -- Update existing user
//   Body: { email, role, displayName, services, features, sites }
// DELETE /api/auth/roles -- Remove a user
//   Body: { email }

Public Endpoints (2)

Available without authentication. Rate-limited to prevent abuse.

Method	Endpoint	Rate Limit	Description
`POST`	`/api/contact`	5/min	Contact form submission. Validates input, rate-limits by IP, sends email via Resend. Returns success/error JSON.
`POST`	`/api/public/chat`	10/min	Public AI chat with a free model. Input is moderated for safety. Responses are limited in length. No conversation history.

Contact Form

// POST /api/contact
// Body:
{
  "name": "Visitor Name",
  "email": "[email protected]",
  "subject": "Question about the homelab",
  "message": "Message body text..."
}

// Response (success):
{ "success": true, "message": "Message sent" }

// Response (rate limited):
// HTTP 429
{ "error": "Too many requests. Try again later." }

Public Chat

// POST /api/public/chat
// Body:
{
  "message": "What is Arcturus-Prime?",
  "model": "free"  // Only the free model is available
}

// Response:
{
  "response": "Arcturus-Prime is a homelab portfolio...",
  "model": "meta-llama/llama-3-8b-instruct",
  "tokensUsed": 156
}

The public chat endpoint uses content moderation to filter inappropriate inputs and limits response tokens to control costs.

Cache Endpoints (2)

Cache management and monitoring.

Method	Endpoint	Auth	Description
`GET`	`/api/cache/status`	Admin	Returns current cache state — in-memory key count, KV key list, oldest/newest entries, hit/miss stats.
`POST`	`/api/cache/warmup`	Secret	Pre-populates caches for critical data. Protected by `CACHE_WARMUP_SECRET` bearer token. Designed for cron triggers.

Cache Warmup

# Trigger cache warmup (typically called by cron)
curl -X POST https://Arcturus-Prime.com/api/cache/warmup \
  -H "Authorization: Bearer ${CACHE_WARMUP_SECRET}"

The warmup endpoint fetches and caches:

Service health checks from all monitored endpoints
User roles from KV
Dashboard widget data
Infrastructure status from the Flask Command Center

Dashboard Endpoints (2)

Dashboard data and configuration.

Method	Endpoint	Auth	Description
`GET` `PUT`	`/api/dashboard/profiles`	Member+	GET returns the user’s dashboard profiles (widget layouts). PUT updates the profile configuration.
`GET`	`/api/dashboard/cf-pages`	Member+	Returns Cloudflare Pages deployment status — latest build, build time, preview URLs, deployment history.

User Portal Endpoints (7)

Authenticated user features.

Method	Endpoint	Auth	Description
`POST`	`/api/user/chat`	Member+	AI chat with full model selection and conversation history. Messages persisted in KV.
`GET`	`/api/user/me`	Member+	Returns the full user profile including preferences, display settings, and feature flags.
`GET`	`/api/user/models`	Member+	Lists available AI models the user can access based on their role and feature permissions.
`GET` `PUT`	`/api/user/preferences`	Member+	User preferences — theme, default model, notification settings, editor config.
`GET` `POST` `DELETE`	`/api/user/files`	Member+	File management — list, upload, and delete files in the user’s workspace.
`POST`	`/api/user/deploy`	Member+	Trigger a site deployment (mirrors Gitea push to rebuild).
`GET`	`/api/user/site-status`	Member+	Returns the current site deployment status and health.

Content Management Endpoints (5)

Admin content CRUD operations.

Method	Endpoint	Auth	Description
`POST`	`/api/admin/mark-reviewed`	Admin	Marks a content entry as reviewed. Sets `reviewed: true` and `reviewedDate` to now.
`GET`	`/api/admin/content-index`	Admin	Returns a full index of all content across all collections — slug, title, status, reviewed, needsWork.
`POST`	`/api/admin/create-content`	Admin	Creates a new content file in the specified collection. Writes to Gitea via API.
`PUT`	`/api/admin/update-content`	Admin	Updates content body for an existing entry. Commits to Gitea.
`PATCH`	`/api/admin/update-frontmatter`	Admin	Updates only the frontmatter of an entry without touching the body. Used for status flags, metadata changes.

Content Index Response

{
  "collections": {
    "posts": [
      {
        "slug": "2026-02-20-tailscale-subnet-routing",
        "title": "Tailscale Subnet Routing Across Two Sites",
        "pubDate": "2026-02-20",
        "reviewed": true,
        "needsWork": false,
        "draft": false,
        "tags": ["tailscale", "networking"]
      }
    ],
    "journal": [...],
    "docs": [...],
    "learn": [...],
    "configurations": [...],
    "projects": [...]
  },
  "totals": {
    "posts": 25,
    "journal": 65,
    "docs": 40,
    "learn": 12,
    "configurations": 8,
    "projects": 6,
    "total": 156
  }
}

AI & Content Generation Endpoints (11)

AI-powered features for content creation, analysis, and assistance.

Method	Endpoint	Auth	Description
`POST`	`/api/admin/chat`	Admin	Admin AI chat with full model selection, system prompts, and persistent conversations.
`POST`	`/api/admin/content-gen`	Admin	Content generation pipeline — takes a topic and generates a full blog post draft with frontmatter.
`POST`	`/api/admin/generate`	Admin	General-purpose AI generation — summaries, rewrites, translations.
`POST`	`/api/admin/generate-image`	Admin	AI image generation for hero images and illustrations.
`GET` `POST` `DELETE`	`/api/admin/conversation`	Admin	Conversation management — list, create, delete AI chat conversations.
`POST`	`/api/admin/ai-coach`	Admin	Writing coach — analyzes draft content and provides feedback on voice, structure, and technical accuracy.
`GET` `POST`	`/api/admin/ai-prompts`	Admin	Prompt library — save, retrieve, and organize reusable AI prompts.
`POST`	`/api/admin/voice-check`	Admin	Analyzes content against the Arcturus-Prime voice guide. Flags AI-sounding patterns and suggests human alternatives.
`POST`	`/api/admin/fact-check`	Admin	Fact-checks technical claims in content against known infrastructure data.
`POST`	`/api/admin/sanitize`	Admin	Runs content through the sanitization pipeline — replaces real hostnames/IPs with galactic identity aliases.
`POST`	`/api/admin/knowledge`	Admin	Knowledge base query — searches across all content collections and returns relevant context.
`POST`	`/api/admin/vault-context`	Admin	Fetches context from Obsidian vaults via Gitea API for AI-assisted content creation.
`POST`	`/api/admin/workflow`	Admin	Orchestrates multi-step content workflows (research, draft, review, publish).

Pipeline Endpoints (3)

Content pipeline and probe management.

Method	Endpoint	Auth	Description
`GET` `POST`	`/api/admin/pipeline`	Admin	Content pipeline status and control — move content through draft/review/publish stages.
`GET` `POST`	`/api/admin/probes`	Admin	Infrastructure probes — health checks, latency tests, connectivity verification.
`GET` `POST`	`/api/admin/probe-export`	Admin	Export/import probe configurations for backup and sharing.

Security Endpoints (2)

Security audit and remote console access.

Method	Endpoint	Auth	Description
`GET` `POST`	`/api/admin/security`	Admin	Security audit tools — scan for exposed services, check SSL certs, verify firewall rules.
`GET` `POST`	`/api/admin/console`	Admin	Proxmox console proxy — opens a VNC/SPICE connection to a VM on Izar-Host (10.42.0.194) or Arcturus-Host (10.42.0.100).

Argonaut Endpoints (9)

The Argonaut AI agent system.

Method	Endpoint	Auth	Description
`POST`	`/api/argonaut/chat`	Admin	Argonaut conversational interface — multi-turn chat with the AI agent.
`POST`	`/api/argonaut/ingest`	Admin	Ingest documents and data into Argonaut’s knowledge base.
`GET` `POST` `DELETE`	`/api/argonaut/memory`	Admin	Argonaut long-term memory management — store, retrieve, forget context.
`GET`	`/api/argonaut/models`	Admin	List AI models available to Argonaut.
`GET` `POST`	`/api/argonaut/profiles`	Admin	Argonaut persona profiles — different system prompts and behaviors.
`POST`	`/api/argonaut/search`	Admin	Semantic search across Argonaut’s knowledge base.
`GET`	`/api/argonaut/status`	Admin	Argonaut system status — model health, memory usage, active sessions.
`GET` `POST`	`/api/argonaut/tasks`	Admin	Task management for Argonaut — assign, track, and complete tasks.
`POST`	`/api/argonaut/voice-score`	Admin	Score content against the Arcturus-Prime voice guidelines using Argonaut’s analysis.

Infrastructure Proxy Endpoints (10)

These endpoints proxy requests to self-hosted infrastructure services, providing a unified API surface through the Arcturus-Prime domain.

Method	Endpoint	Auth	Proxies To	Description
`*`	`/api/proxy`	Admin	Various	General-purpose proxy — forwards requests to any configured backend service.
`*`	`/api/gateway`	Admin	10.42.0.199:8090	Build swarm gateway on Altair-Link. Status, binhost resolution, build submission.
`*`	`/api/command`	Admin	Altair-Link:8093	Flask Command Center — system status, Docker management, storage overview.
`*`	`/api/orchestrator`	Admin	10.42.0.201:8091	Build swarm orchestrator — build status, package tracking, drone management.
`GET`	`/api/services`	Admin	Multiple	Aggregated service health from all monitored endpoints.
`*`	`/api/swarm`	Admin	10.42.0.199:8090	Build swarm API — submit builds, check progress, manage drones.
`*`	`/api/swarm-admin`	Admin	10.42.0.201:8091	Direct orchestrator admin access — finalize builds, reset state, balance work.
`*`	`/api/mm-Arcturus-Prime`	Admin	10.42.0.199	Monitoring and metrics for Altair-Link services.
`*`	`/api/Tarn-Host-adminbox`	Admin	192.168.20.118	Proxmox Tarn-Host admin proxy — remote hypervisor management via Tailscale.
`*`	`/api/uptime-kuma`	Admin	Altair-Link:3001	Uptime Kuma API proxy — monitor status, incidents, heartbeat data.

Proxy Architecture

Infrastructure proxies follow a consistent pattern:

// Generic proxy handler
export async function ALL({ request, locals }: APIContext) {
  const user = locals.user;
  if (!user || user.role !== 'admin') {
    return new Response('Forbidden', { status: 403 });
  }

  const targetUrl = new URL(request.url);
  targetUrl.hostname = BACKEND_HOST;
  targetUrl.port = BACKEND_PORT;

  const proxyResponse = await fetch(targetUrl.toString(), {
    method: request.method,
    headers: request.headers,
    body: request.body,
  });

  return new Response(proxyResponse.body, {
    status: proxyResponse.status,
    headers: proxyResponse.headers,
  });
}

The proxies strip authentication headers before forwarding (backend services run on the private network and do not expect Cloudflare Access tokens). CORS headers are added to responses so the admin panel frontend can make cross-origin requests.

Error Response Format

All API endpoints return errors in a consistent JSON format:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "status": 400
}

Common error codes:

Status	Code	Meaning
400	`BAD_REQUEST`	Missing or invalid request body/params
401	`UNAUTHORIZED`	No valid authentication credentials
403	`FORBIDDEN`	Authenticated but insufficient permissions
404	`NOT_FOUND`	Resource does not exist
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Server-side failure

API Route File Structure

src/pages/api/
├── auth/
│   ├── me.ts              # /api/auth/me
│   └── roles.ts           # /api/auth/roles
├── contact.ts             # /api/contact
├── public/
│   └── chat.ts            # /api/public/chat
├── cache/
│   ├── status.ts          # /api/cache/status
│   └── warmup.ts          # /api/cache/warmup
├── dashboard/
│   ├── profiles.ts        # /api/dashboard/profiles
│   └── cf-pages.ts        # /api/dashboard/cf-pages
├── user/
│   ├── chat.ts            # /api/user/chat
│   ├── me.ts              # /api/user/me
│   ├── models.ts          # /api/user/models
│   ├── preferences.ts     # /api/user/preferences
│   ├── files.ts           # /api/user/files
│   ├── deploy.ts          # /api/user/deploy
│   └── site-status.ts     # /api/user/site-status
├── admin/
│   ├── chat.ts            # /api/admin/chat
│   ├── content-gen.ts     # /api/admin/content-gen
│   ├── generate.ts        # /api/admin/generate
│   ├── generate-image.ts  # /api/admin/generate-image
│   ├── conversation.ts    # /api/admin/conversation
│   ├── ai-coach.ts        # /api/admin/ai-coach
│   ├── ai-prompts.ts      # /api/admin/ai-prompts
│   ├── voice-check.ts     # /api/admin/voice-check
│   ├── fact-check.ts      # /api/admin/fact-check
│   ├── sanitize.ts        # /api/admin/sanitize
│   ├── knowledge.ts       # /api/admin/knowledge
│   ├── vault-context.ts   # /api/admin/vault-context
│   ├── workflow.ts         # /api/admin/workflow
│   ├── mark-reviewed.ts   # /api/admin/mark-reviewed
│   ├── content-index.ts   # /api/admin/content-index
│   ├── create-content.ts  # /api/admin/create-content
│   ├── update-content.ts  # /api/admin/update-content
│   ├── update-frontmatter.ts # /api/admin/update-frontmatter
│   ├── pipeline.ts        # /api/admin/pipeline
│   ├── probes.ts          # /api/admin/probes
│   ├── probe-export.ts    # /api/admin/probe-export
│   ├── security.ts        # /api/admin/security
│   └── console.ts         # /api/admin/console
├── argonaut/
│   ├── chat.ts            # /api/argonaut/chat
│   ├── ingest.ts          # /api/argonaut/ingest
│   ├── memory.ts          # /api/argonaut/memory
│   ├── models.ts          # /api/argonaut/models
│   ├── profiles.ts        # /api/argonaut/profiles
│   ├── search.ts          # /api/argonaut/search
│   ├── status.ts          # /api/argonaut/status
│   ├── tasks.ts           # /api/argonaut/tasks
│   └── voice-score.ts     # /api/argonaut/voice-score
├── proxy.ts               # /api/proxy
├── gateway.ts             # /api/gateway
├── command.ts             # /api/command
├── orchestrator.ts        # /api/orchestrator
├── services.ts            # /api/services
├── swarm.ts               # /api/swarm
├── swarm-admin.ts         # /api/swarm-admin
├── mm-Arcturus-Prime.ts          # /api/mm-Arcturus-Prime
├── Tarn-Host-adminbox.ts      # /api/Tarn-Host-adminbox
└── uptime-kuma.ts         # /api/uptime-kuma