API Endpoints

ArgoBox 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": "visitor@example.com",
  "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 ArgoBox?",
  "model": "free"  // Only the free model is available
}

// Response:
{
  "response": "ArgoBox 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://argobox.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 ArgoBox 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 proxmox-io (10.0.0.194) or proxmox-argobox (10.0.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 ArgoBox 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 ArgoBox 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.0.0.199:8090	Build swarm gateway on argobox-lite. Status, binhost resolution, build submission.
*	/api/command	Admin	argobox-lite:8093	Flask Command Center -- system status, Docker management, storage overview.
*	/api/orchestrator	Admin	10.0.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.0.0.199:8090	Build swarm API -- submit builds, check progress, manage drones.
*	/api/swarm-admin	Admin	10.0.0.201:8091	Direct orchestrator admin access -- finalize builds, reset state, balance work.
*	/api/mm-argobox	Admin	10.0.0.199	Monitoring and metrics for argobox-lite services.
*	/api/titan-adminbox	Admin	192.168.50.118	Proxmox Titan admin proxy -- remote hypervisor management via Tailscale.
*	/api/uptime-kuma	Admin	argobox-lite: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-argobox.ts          # /api/mm-argobox
├── titan-adminbox.ts      # /api/titan-adminbox
└── uptime-kuma.ts         # /api/uptime-kuma